Add new topic about creating pull requests (#71)

Author: tomschr

changelog.d/71.doc.rst

@@ -0,0 +1 @@
+Add new topic about creating pull requests

docs/source/developer/create-pullrequests.rst

@@ -0,0 +1,35 @@
+.. _create-prs:
+
+Create Pull Requests
+====================
+
+This section outlines the steps for creating pull requests (PRs) for this project.
+
+It is assumed that you already cloned or forked this repostitory and have a working development environment set up.
+
+Follow these steps to create a pull request:
+
+#. On the GitHub project, find a bug or feature you want to work on.
+#. In your local repository, create a new branch for your changes.
+
+   It's recommended to use the issue number and a descriptive name for the branch that reflects the changes you plan to make.
+#. Make your changes in the codebase.
+
+   * Ensure that you :ref:`run the test suite <run-testsuite>`.
+   * Watch for the :ref:`coverage report <interprete-coverage>` and try to keep the coverage high.
+   * Enhance the documentation if it's a user-facing change.
+#. Commit your changes with a clear and concise commit message.
+
+   * Include the issue number if applicable and add phrases like ``Fixes #123``.
+   * It's enough to have a high-level description of the changes.
+   * The message should explain *why* these changes were necessary.
+#. Push your changes and create a pull request On GitHub. GitHub creates a pull request number for you.
+#. If useful, :ref:`create a news fragment <add-newsfragments>` of your changes.
+
+   This is important for the changelog generation. Push the news fragment to the same branch as your changes.
+#. On GitHub, request a review.
+#. Address any feedback from the review.
+
+   * Make additional commits to your branch as needed.
+   * Ensure that the test suite passes after your changes.
+#. Once the review is complete and all tests pass, squash merge your branch into the main branch.

docs/source/developer/index.rst

@@ -18,6 +18,7 @@ This guide provides all the necessary information for contributing to the projec
    prepare-environment
    install-vscode
    develop-project
+   create-pullrequests
    run-testsuite
    update-package
    bump-version
@@ -26,7 +27,7 @@ This guide provides all the necessary information for contributing to the projec
    build-changelog
    create-release
    trigger-actions
-   
+
    build-docs
    howto
 
@@ -35,4 +36,4 @@ This guide provides all the necessary information for contributing to the projec
    :caption: Appendix
 
    know-tools-config
-   knowing-github-setup
+   knowing-github-setup

docs/source/developer/run-testsuite.rst

@@ -1,8 +1,14 @@
+.. _run-testsuite:
+
 Running the Test Suite
 ======================
 
 To run the test suite for this project, you need to have completed the setup of your development environment as described in the :ref:`prepare-devel-env` topic.
 
+
+Running the full test suite
+----------------------------
+
 To run the full test suite, use the following command:
 
 .. code-block:: shell-session
@@ -21,6 +27,9 @@ or use the alias (see :ref:`devel-helpers` for more information):
 
 This command will execute all the tests defined in the project. The test suite is designed to ensure that all components of the project are functioning correctly and to catch any regressions.
 
+Running specific tests
+----------------------
+
 In case you want to run a specific test or a subset of tests, specify the path to the test file or the test function. For example:
 
 .. code-block:: shell-session
@@ -32,10 +41,39 @@ In case you want to run a specific test or a subset of tests, specify the path t
 
 In the first example, all tests in `test_module.py` will be executed, while in the second example, only the specific test function `test_function_name` will be run.
 
+Running failed tests only
+-------------------------
+
 If one of the test fails and you want to repeat the test run after you have fixed the issue, use the ``--lf``/``--last-failed`` option. For example:
 
 .. code-block:: shell-session
    :caption: Running only the last failed tests
    :name: running-last-failed-tests
 
-   upytest --lf
+   upytest --lf
+
+
+.. _interprete-coverage:
+
+Interpreting coverage
+---------------------
+
+Coverage is a measure of how much of your code is executed during the tests. The coverage report is only generated when all tests pass.
+
+.. code-block:: text
+   :caption: Coverate report
+
+   [...]
+   src/docbuild/cli/cmd_validate/process.py  142      3     42      2  97.3%   217->219, 299-303
+   [...]
+   src/docbuild/utils/doc.py                  20      0      0      0 100.0%
+   src/docbuild/utils/merge.py                74      0     34      0 100.0%
+   src/docbuild/utils/paths.py                13      0      6      0 100.0%
+   --------------------------------------------------------------------------
+   TOTAL                                    1866     23    478      6  98.6%
+
+If you look through the report, you will see which lines are not covered by tests indicated by a test coverage lower than 100%. The numbers in the report indicate the line numbers where the code is not executed during the tests.
+
+In this example, the coverage report shows that 98.6% of the code is covered by tests. The file :file:`src/docbuild/cli/cmd_validate/process.py` has a coverage of 97.3%, meaning that some lines in this file are not executed during the tests. These lines are indicated by the numbers in the report, such as ``217->219`` and ``299-303``.
+
+Depending on your code, you might want to improve the test coverage by adding more tests for the uncovered lines. This will help ensure that your code is thoroughly tested and behaves as expected.