Merge pull request #1672 from aucampia/iwana-20220114T2135-precommit_ci

pre-commit and pre-commit-ci

.pre-commit-config.yaml

@@ -0,0 +1,25 @@
+---
+ci:
+  # https://pre-commit.ci/#configuration
+  autoupdate_schedule: weekly
+  autofix_prs: false
+
+repos:
+  - repo: local
+    hooks:
+    # using a local hook for black because of an issue that arises when using
+    # pre-commit and setuptools-scm that results in version info being lost.
+    # For more info see https://github.com/psf/black/issues/2493
+    # Based on https://github.com/psf/black/blob/main/.pre-commit-hooks.yaml
+    - id: black
+      name: black
+      description: "Black: The uncompromising Python code formatter"
+      entry: black
+      language: python
+      # WARNING: version should be the same as in `pyproject.toml`.
+      additional_dependencies: [black==21.9b0]
+      # This is here to defer file selection to black which will do it based on
+      # black config.
+      pass_filenames: false
+      require_serial: true
+      args: ["."]

docs/developers.rst

@@ -108,6 +108,46 @@ Check types with `mypy <http://mypy-lang.org/>`_:
 
     python -m mypy --show-error-context --show-error-codes rdflib
 
+pre-commit and pre-commit ci
+----------------------------
+
+We have `pre-commit <https://pre-commit.com/>`_ configured with `black
+<https://github.com/psf/black>`_ for formatting code.
+
+Some useful commands for using pre-commit:
+
+.. code-block:: bash
+
+    # Install pre-commit.
+    pip install --user --upgrade pre-commit
+
+    # Install pre-commit hooks, this will run pre-commit
+    # every time you make a git commit.
+    pre-commit install
+
+    # Run pre-commit on changed files.
+    pre-commit run
+
+    # Run pre-commit on all files.
+    pre-commit run --all-files
+
+There is also two tox environments for pre-commit:
+
+.. code-block:: bash
+
+    # run pre-commit on changed files.
+    tox -e precommit
+
+    # run pre-commit on all files.
+    tox -e precommitall
+
+
+There is no hard requirement for pull requests to be processed with pre-commit (or the underlying processors), however doing this makes for a less noisy codebase with cleaner history.
+
+We have enabled `https://pre-commit.ci/ <https://pre-commit.ci/>`_ and this can
+be used to automatically fix pull requests by commenting ``pre-commit.ci
+autofix`` on a pull request.
+
 Using tox
 ---------------------
 

pyproject.toml

@@ -1,4 +1,5 @@
 [tool.black]
+# WARNING: This should be the same as in `.pre-commit-config.yaml`.
 required-version = "21.9b0"
 line-length = "88"
 skip-string-normalization = true

tox.ini

@@ -1,6 +1,6 @@
 [tox]
 envlist =
-    py37,py38,py39,py310
+    py37,py38,py39,py310,precommit
 
 [testenv]
 setenv =
@@ -46,6 +46,14 @@ setenv =
 commands =
     sphinx-build -n -T -b html -d {envtmpdir}/doctrees docs docs/_build/html
 
+[testenv:precommit{,all}]
+skip_install = true
+deps = pre-commit
+passenv = HOMEPATH  # needed on Windows
+commands =
+    precommit: pre-commit run
+    precommitall: pre-commit run --all-files
+
 [pytest]
 # log_cli = true
 # log_cli_level = DEBUG