Merge pull request #3571 from nicoddemus/pre-commit-contributors-guide

Improve contributing instructions regarding black/linting

CONTRIBUTING.rst

@@ -162,11 +162,11 @@ Preparing Pull Requests
 Short version
 ~~~~~~~~~~~~~
 
-#. Fork the repository;
+#. Fork the repository.
-#. enable and install pre-commit https://pre-commit.com/ to ensure styleguides and codechecks are followed
+#. Enable and install `pre-commit <https://pre-commit.com>`_ to ensure style-guides and code checks are followed.
-#. Target ``master`` for bugfixes and doc changes;
+#. Target ``master`` for bugfixes and doc changes.
 #. Target ``features`` for new features or functionality changes.
-#. Follow **PEP-8**. There's a ``tox`` command to help fixing it: ``tox -e fix-lint``.
+#. Follow **PEP-8** for naming and `black <https://github.com/ambv/black>`_ for formatting.
 #. Tests are run using ``tox``::
 
     tox -e linting,py27,py36
@@ -177,7 +177,7 @@ Short version
    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;
+   add yourself to the ``AUTHORS`` file, in alphabetical order.
 
 
 Long version
@@ -217,15 +217,15 @@ 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 install its hook on the pytest repo
+#. Install `pre-commit <https://pre-commit.com>`_ and its hook on the pytest repo::
 
-    https://pre-commit.com/ is a framework for managing and maintaining multi-language pre-commit hooks
+     $ pip install --user pre-commit
-    pytest uses pre-commit to ensure code-style and code formatting is the same
+     $ pre-commit install
 
-    $ pip install --user pre-commit
+   Afterwards ``pre-commit`` will run whenever you commit.
-    $ pre-commit install
 
-    Afterwards pre-commit will run whenever you commit.
+   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.
 
 #. Install tox
 
@@ -245,15 +245,7 @@ Here is a simple overview, with pytest-specific bits:
    This command will run tests via the "tox" tool against Python 2.7 and 3.6
    and also perform "lint" coding-style checks.
 
-#. You can now edit your local working copy. Please follow PEP-8.
+#. You can now edit your local working copy and run the tests again as necessary. Please follow PEP-8 for naming.
-
-   You can now make the changes you want and run the tests again as necessary.
-
-   If you have too much linting errors, try running::
-
-    $ tox -e fix-lint
-
-   To fix pep8 related errors.
 
    You can pass different options to ``tox``. For example, to run tests on Python 2.7 and pass options to pytest
    (e.g. enter pdb on failure) to pytest you can do::
@@ -264,6 +256,9 @@ Here is a simple overview, with pytest-specific bits:
 
     $ tox -e py36 -- testing/test_config.py
 
+
+   When committing, ``pre-commit`` will re-format the files if necessary.
+
 #. Commit and push once your tests pass and you are happy with your change(s)::
 
     $ git commit -a -m "<commit message>"