misc: Add steps for automatically fixing errors to contributing and pre-commit-config

Author: JDBetteridge

.pre-commit-config.yaml

@@ -1,5 +1,5 @@
 # See https://pre-commit.com for more information
-# See https://pre-commit.com/hooks.html for more hooks
+default_stages: [pre-commit]
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v3.2.0
@@ -13,23 +13,28 @@ repos:
     hooks:
       # Run isort to check only (don't modify files)
       - id: isort
+        name: "Check imports are sorted"
         args: [--check-only, --filter-files]
+        stages: [pre-commit]
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
     rev: v0.14.4
     hooks:
       # Run the linter to check only (don't modify files)
       - id: ruff-check
+        name: "Check code is linted with ruff"
   - repo: https://github.com/PyCQA/flake8
     rev: 7.3.0
     hooks:
       - id: flake8
+        name: "Check code is linted with flake8"
         additional_dependencies: [flake8-pyproject]
   - repo: https://github.com/crate-ci/typos
     rev: v1.39.1
     hooks:
       - id: typos
-        args: []
+        name: "Check files for typos"
+        stages: [pre-commit]
   - repo: https://github.com/rhysd/actionlint
     rev: v1.7.8
     hooks:
@@ -39,3 +44,33 @@ repos:
     hooks:
       - id: hadolint-docker
         entry: -e HADOLINT_IGNORE=DL3003,DL3004,DL3005,DL3007,DL3008,DL3009,DL3013,DL3015,DL3042,DL3059,SC2103,SC2046,SC2086 ghcr.io/hadolint/hadolint hadolint
+  #
+  # These stages modify the files applying fixes where possible
+  # Since this may be undesirable they will not run automatically
+  # These stages can be run with
+  # pre-commit run --hook-stage manual
+  #
+  - repo: https://github.com/pycqa/isort
+    rev: 5.13.2
+    hooks:
+      # Run isort to check only (don't modify files)
+      - id: isort
+        name: "Fix imports with isort"
+        args: [--filter-files]
+        stages: [manual]
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.14.4
+    hooks:
+      # Run the linter to check only (don't modify files)
+      - id: ruff-check
+        name: "Fix linting errors with ruff check --fix"
+        args: [--fix]
+        stages: [manual]
+  - repo: https://github.com/crate-ci/typos
+    rev: v1.39.1
+    hooks:
+      - id: typos
+        name: "Fix typos"
+        args: [-w]
+        stages: [manual]

CONTRIBUTING.md

@@ -110,7 +110,7 @@ These checks will:
 * Lint GitHub Actions workflow files using actionlint *
 * Lint Dockerfiles using hadolint *
 
-(* these checks will not change the edited files, you must manually fix the files or run an automated tool eg: `ruff check --fix`)
+(* these checks will not change the edited files, you must manually fix the files or run an automated tool eg: `ruff check --fix` see below for details)
 
 If you absolutely must push "dirty" code, `pre-commit` can be circumvented using:
 ```bash
@@ -133,6 +133,23 @@ Some coding rules are "enforced" (and automatically checked by CI), some are "st
   - Comment your code, and do not be afraid of being verbose. The first letter must be capitalized. Do not use punctuation (unless the comment consists of multiple sentences).
 * We _like_ that blank lines are used to logically split blocks of code implementing different (possibly sequential) tasks.
 
+#### Pre-commit
+
+You can use `pre-commit` to apply automated fixes for line endings, ends of files, import sorting and ruff linting.
+All of these steps can be run together on your changes by running:
+```bash
+pre-commit run --hook-stage manual
+```
+Adding the `-a` flag runs this on all files in the repository, not just the files that you have changed.
+Adding the name of the stage will run just one check.
+See the [pre-commit-config](https://github.com/devitocodes/devito/blob/main/.pre-commit.yaml) file for the names of stages.
+
+Some fixes can be automatically applied by the ruff linter, but may change the code in undesirable ways.
+This step can only be run manually:
+```bash
+ruff check --fix --unsafe-fixes
+```
+
 ### Adding tutorials or examples
 
 We always look forward to extending our [suite of tutorials and examples](https://www.devitoproject.org/devito/tutorials.html) with new Jupyter Notebooks.