diff mbox series

docs: Add documentation for pre-commit

Message ID 20190927080830.20030-1-stephen@that.guru
State Accepted
Headers show
Series docs: Add documentation for pre-commit | expand

Commit Message

Stephen Finucane Sept. 27, 2019, 8:08 a.m. UTC 
Explain what it is and why you should use it.

Signed-off-by: Stephen Finucane <stephen@that.guru>
---
 docs/development/contributing.rst | 27 +++++++++++++++++++++++----
 1 file changed, 23 insertions(+), 4 deletions(-)

Comments

Stephen Finucane Oct. 5, 2019, 2:50 p.m. UTC | #1 
On Fri, 2019-09-27 at 09:08 +0100, Stephen Finucane wrote:
> Explain what it is and why you should use it.
> 
> Signed-off-by: Stephen Finucane <stephen@that.guru>

Applied.
diff mbox series

Patch

diff --git a/docs/development/contributing.rst b/docs/development/contributing.rst
index 5089bba8..50171608 100644
--- a/docs/development/contributing.rst
+++ b/docs/development/contributing.rst
@@ -19,11 +19,29 @@  files and may be added for significant changes to existing files.
    #
    # SPDX-License-Identifier: GPL-2.0-or-later
 
-Changes that fix semantic issues will be generally be happily received, but
-please keep such changes separate from functional changes.
+Changes that fix semantic issues will be happily received, but please keep such
+changes separate from functional changes.
 
-``pep8`` targets are provided via tox. Refer to the :ref:`testing` section
-below for more information on usage of this tool.
+Patchwork uses the `pre-commit`_ framework to allow automated style checks when
+committing code. This is opt-in but avoids the need to manually run style
+checks on commits. Pre-commit can be installed and enabled like so:
+
+.. code-block:: shell
+
+   $ pip install --user pre-commit
+   $ pre-commit install --allow-missing-config
+
+Once installed, the various checks listed in ``.pre-commit-config.yaml`` will
+be run on changed files when committing. It is also possible to run the checks
+on all files manually:
+
+.. code-block:: shell
+
+   $ pre-commit run --all-files
+
+In addition to *pre-commit*, we provide *tox* targets for style checks. These
+are used by CI and can be useful if checking all files manually. Refer to the
+:ref:`testing` section below for more information on usage of this tool.
 
 .. _testing:
 
@@ -163,6 +181,7 @@  Further information about the Patchwork mailing list is available can be found o
 .. _PEP 8: https://pep8.org/
 .. _GPL v2.0 or later: https://spdx.org/licenses/GPL-2.0-or-later.html
 .. _SPDX License Identifier: https://spdx.org/using-spdx-license-identifier
+.. _pre-commit: https://pre-commit.com/
 .. _tox: https://tox.readthedocs.io/en/latest/
 .. _reno: https://docs.openstack.org/developer/reno/
 .. _QEMU guidelines: http://wiki.qemu.org/Contribute/SubmitAPatch