diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 57921de2f6a..5dc9a1d9821 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -158,40 +158,21 @@ As stated, the objective is to share maintenance and avoid "plugin-abandon". .. _`pull requests`: .. _pull-requests: -Preparing Pull Requests +Creating a pull request ----------------------- -Short version -~~~~~~~~~~~~~ - -#. Fork the repository. -#. Enable and install `pre-commit `_ to ensure style-guides and code checks are followed. -#. Follow **PEP-8** for naming and `black `_ for formatting. -#. Tests are run using ``tox``:: - - tox -e linting,py37 - - The test environments above are usually enough to cover most cases locally. - -#. Write a ``changelog`` entry: ``changelog/2574.bugfix.rst``, use issue id number - and one of ``bugfix``, ``removal``, ``feature``, ``vendor``, ``doc`` or - ``trivial`` for the issue type. -#. Unless your change is a trivial or a documentation fix (e.g., a typo or reword of a small section) please - add yourself to the ``AUTHORS`` file, in alphabetical order. +.. note:: + See the `GitHub Tutorial on pull requests `_. + for an introduction on what pull requests are. -Long version -~~~~~~~~~~~~ +.. note:: -What is a "pull request"? It informs the project's core developers about the -changes you want to review and merge. Pull requests are stored on -`GitHub servers `_. -Once you send a pull request, we can discuss its potential modifications and -even add more commits to it later on. There's an excellent tutorial on how Pull -Requests work in the -`GitHub Help Center `_. + `flake8`_ (enforcing :pep:`8`) and `black`_ are used to ensure a + consistent code style. -Here is a simple overview, with pytest-specific bits: +.. _flake8: https://pypi.org/project/flake8/ +.. _black: https://github.com/psf/black #. Fork the `pytest GitHub repository `__. It's @@ -213,51 +194,54 @@ Here is a simple overview, with pytest-specific bits: If you need some help with Git, follow this quick start guide: https://git.wiki.kernel.org/index.php/QuickStart -#. Install `pre-commit `_ and its hook on the pytest repo: +#. **Optionally** install and enable `pre-commit `_ - **Note: pre-commit must be installed as admin, as it will not function otherwise**:: + https://pre-commit.com/ is a framework for managing and maintaining multi-language pre-commit hooks + to ensure code-style and code formatting is consistent. - $ pip install --user pre-commit - $ pre-commit install + Installing it will run checks whenever you commit, which slows things down + however, and might cause conflicts, e.g. between ``black`` changing files + in a way ``flake8`` does not like them. - Afterwards ``pre-commit`` will run whenever you commit. + Therefore it is usually better to run it via ``tox -e linting`` manually, + when you are finished with your changes. - https://pre-commit.com/ is a framework for managing and maintaining multi-language pre-commit hooks - to ensure code-style and code formatting is consistent. + $ pip install --user pre-commit + $ pre-commit install #. Install tox - Tox is used to run all the tests and will automatically setup virtualenvs - to run the tests in. - (will implicitly use http://www.virtualenv.org/en/latest/):: + Tox is used to run the tests in an isolated environment with automatically + created virtualenvs:: $ pip install tox + You can also use a virtualenv directly (see below). + #. Run all the tests - You need to have Python 3.7 available in your system. Now - running tests is as simple as issuing this command:: + The following example uses Python 3.7, which needs to be available on + your system. - $ tox -e linting,py37 + To run all tests and additional linting checks:: - This command will run tests via the "tox" tool against Python 3.7 - and also perform "lint" coding-style checks. + $ tox -e py37,linting -#. You can now edit your local working copy and run the tests again as necessary. Please follow PEP-8 for naming. +#. You can now edit your local working copy and run the tests again as necessary. - You can pass different options to ``tox``. For example, to run tests on Python 3.7 and pass options to pytest + You can pass different options to ``tox``, and especially the ``pytest`` + run by ``tox``. + For example, to run tests on Python 3.8 and pass options to pytest (e.g. enter pdb on failure) to pytest you can do:: - $ tox -e py37 -- --pdb + $ tox -e py38 -- --pdb Or to only run tests in a particular test module on Python 3.7:: $ tox -e py37 -- testing/test_config.py - - When committing, ``pre-commit`` will re-format the files if necessary. - -#. If instead of using ``tox`` you prefer to run the tests directly, then we suggest to create a virtual environment and use +#. If instead of using ``tox`` you prefer to run the tests directly, then + you can create a virtual environment and use an editable install with the ``testing`` extra:: $ python3 -m venv .venv @@ -269,18 +253,23 @@ Here is a simple overview, with pytest-specific bits: $ pytest testing/test_config.py +#. Create a new changelog entry in the ``changelog`` directory. + The file should be named ``..rst``, + where *issueid* is the number of the issue (or pull request) related + to the change and *type* is one of + ``bugfix``, ``removal``, ``feature``, ``vendor``, ``doc`` or ``trivial``, + e.g. ``changelog/2574.bugfix.rst``. + + You can skip creating a changelog entry if the change doesn't affect the + documented behaviour of Pytest. #. Commit and push once your tests pass and you are happy with your change(s):: $ git commit -a -m "" $ git push -u -#. Create a new changelog entry in ``changelog``. The file should be named ``..rst``, - where *issueid* is the number of the issue related to the change and *type* is one of - ``bugfix``, ``removal``, ``feature``, ``vendor``, ``doc`` or ``trivial``. You may not create a - changelog entry if the change doesn't affect the documented behaviour of Pytest. - -#. Add yourself to ``AUTHORS`` file if not there yet, in alphabetical order. +#. Consider adding yourself to the ``AUTHORS`` file in alphabetical order, + unless your change is trivial. #. Finally, submit a pull request through the GitHub website using this data:: diff --git a/changelog/6877.doc.rst b/changelog/6877.doc.rst new file mode 100644 index 00000000000..bc6151e938a --- /dev/null +++ b/changelog/6877.doc.rst @@ -0,0 +1,5 @@ +Improve :ref:`pull-requests` in ``CONTRIBUTING.rst`` + +Started with not +`enforcing pre-commit `_, +but then also merged "short" and "long" version.