Merge pull request #3315 from boutproject/pre-commit-hooks

ZedThree · web-flow · commit 82fe1de5a16b · 2026-03-12T09:42:47.000Z
Consistent developer tooling; refactor formatting CI
diff --git a/.clang-format b/.clang-format
@@ -93,6 +93,7 @@ PenaltyBreakString: 1000
 PenaltyExcessCharacter: 1000000
 PenaltyReturnTypeOnItsOwnLine: 60
 PointerAlignment: Left
+QualifierAlignment: Left
 ReflowComments:  false
 SortIncludes:    true
 # SortUsingDeclarations: true
diff --git a/.clang-tidy b/.clang-tidy
@@ -1,5 +1,5 @@
 ---
-Checks:          'clang-diagnostic-*,clang-analyzer-*,performance-*,readability-*,bugprone-*,clang-analyzer-*,cppcoreguidelines-*,mpi-*,misc-*,-readability-magic-numbers,-cppcoreguidelines-avoid-magic-numbers,-misc-non-private-member-variables-in-classes,-clang-analyzer-optin.mpi*,-bugprone-exception-escape,-cppcoreguidelines-pro-bounds-pointer-arithmetic,-readability-function-cognitive-complexity,-misc-no-recursion,-bugprone-easily-swappable-parameters,-readability-identifier-length'
+Checks:          'clang-diagnostic-*,clang-analyzer-*,performance-*,readability-*,bugprone-*,clang-analyzer-*,cppcoreguidelines-*,mpi-*,misc-*,-readability-magic-numbers,-cppcoreguidelines-avoid-magic-numbers,-misc-non-private-member-variables-in-classes,-clang-analyzer-optin.mpi*,-bugprone-exception-escape,-cppcoreguidelines-pro-bounds-pointer-arithmetic,-readability-function-cognitive-complexity,-misc-no-recursion,-bugprone-easily-swappable-parameters,-readability-identifier-length,-cppcoreguidelines-pro-bounds-avoid-unchecked-container-access'
 WarningsAsErrors: ''
 HeaderFilterRegex: ''
 FormatStyle:     file
@@ -29,6 +29,7 @@ These are all basically unavoidable in HPC numeric code:
 -readability-magic-numbers
 -cppcoreguidelines-avoid-magic-numbers
 -cppcoreguidelines-pro-bounds-pointer-arithmetic
+-cppcoreguidelines-pro-bounds-avoid-unchecked-container-access
 -readability-function-cognitive-complexity
 -bugprone-easily-swappable-parameters
 -readability-identifier-length
diff --git a/.clangd b/.clangd
@@ -0,0 +1,6 @@
+Diagnostics:
+  MissingIncludes: Strict
+  ClangTidy:
+    FastCheckFilter: None
+  Includes:
+    IgnoreHeader: ["adios2/.*", "bits/.*", "cpptrace/.*", "petsc.*"]
diff --git a/.github/workflows/auto-formatting.yml b/.github/workflows/auto-formatting.yml
@@ -15,48 +15,19 @@ jobs:
           ref: ${{ github.head_ref }}
           fetch-depth: 0
 
-      # This also installs git-clang-format
-      - name: Install formatters
-        run: |
-          sudo apt install clang-format python3-pip python3-setuptools python3-wheel
-          pip3 install ruff cmake-format
+      - name: "Set up Python"
+        uses: actions/setup-python@v6
 
-      - name: Version
-        run: |
-          python3 --version
-          $HOME/.local/bin/ruff --version
-          clang-format --version
-          $HOME/.local/bin/cmake-format --version
-
-      - name: Run clang-format
-        id: format
-        run:
-          while ! git clang-format origin/${{ github.base_ref }} ; do git add . ; done
-
-      - name: Run ruff
-        run: |
-          pwd
-          ls
-          $HOME/.local/bin/ruff format .
-          
-      - name: Run cmake-format
-        run: |
-          pwd
-          ls
-          $HOME/.local/bin/cmake-format -i $(find -name CMakeLists.txt) cmake/*.cmake
-
-      - name: Commit formatting
-        uses: stefanzweifel/git-auto-commit-action@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
         with:
-          commit_message: "[bot] Apply format changes"
-          skip_push: true
+          enable-cache: true
 
-      - name: Ignore formatting
-        run: |
-          msg=$(git rev-list --format=%s --max-count=1 HEAD|tail -n -1)
-          test "$msg" = "[bot] Apply format changes" && git rev-parse HEAD >> .git-blame-ignore-revs || :
+      - name: Install dev tools
+        run: uv sync --only-dev
 
-      - name: Commit formatting
-        uses: stefanzweifel/git-auto-commit-action@v7
-        with:
-          commit_message: "[bot] Add last format changes commit to ignore file"
+      - name: Check prek versions are up-to-date
+        run: uv tool run sync-with-uv --check --diff
+
+      - name: Run everything
+        run: uv tool run prek run --show-diff-on-failure --from-ref origin/${{ github.base_ref }}
diff --git a/.github/workflows/clang-tidy-review.yml b/.github/workflows/clang-tidy-review.yml
@@ -24,6 +24,7 @@ jobs:
         uses: ZedThree/clang-tidy-review@v0.23.1
         id: review
         with:
+          annotations: true
           build_dir: build
           apt_packages: "libfftw3-dev,libnetcdf-c++4-dev,libopenmpi-dev,petsc-dev,slepc-dev,liblapack-dev,libparpack2-dev,libsundials-dev,uuid-dev"
           config_file: ".clang-tidy"
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -0,0 +1,62 @@
+# This file requires prek rather than pre-commit
+exclude:
+  glob:
+    - "tools/**/*.pro"
+    - "tools/**/*.m"
+    - "tools/**/*.[ch]"
+
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+- repo: builtin
+  hooks:
+    - id: trailing-whitespace
+    - id: end-of-file-fixer
+    - id: check-added-large-files
+
+# This would be nice to use, but it is a significant slowdown:
+
+# # Sync versions of hook tools with `uv.lock`
+# - repo: https://github.com/tsvikas/sync-with-uv
+#   rev: v0.5.0
+#   hooks:
+#     - id: sync-with-uv
+
+# C++ formatting
+- repo: https://github.com/pre-commit/mirrors-clang-format
+  rev: v22.1.0
+  hooks:
+  - id: clang-format
+    types_or: [c++, c, cuda]
+
+# Python linting and formatting
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.15.5
+  hooks:
+    # Run the linter.
+    - id: ruff-check
+    # Run the formatter.
+    - id: ruff-format
+
+# CMake formatting
+- repo: https://github.com/cheshirekow/cmake-format-precommit
+  rev: v0.6.13
+  hooks:
+    - id: cmake-format
+      additional_dependencies: [pyyaml>=5.1]
+
+# Various config files
+- repo: https://github.com/python-jsonschema/check-jsonschema
+  rev: 0.37.0
+  hooks:
+    - id: check-github-workflows
+    - id: check-readthedocs
+    - id: check-citation-file-format
+    - id: check-dependabot
+
+# Docs linting
+- repo: https://github.com/sphinx-contrib/sphinx-lint
+  rev: v1.0.2
+  hooks:
+    - id: sphinx-lint
+      files: 'manual/sphinx/.*'
diff --git a/manual/sphinx/conf.py b/manual/sphinx/conf.py
@@ -192,7 +192,7 @@ def __getattr__(cls, name):
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".venv", "venv"]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
diff --git a/manual/sphinx/developer_docs/contributing.rst b/manual/sphinx/developer_docs/contributing.rst
@@ -173,6 +173,78 @@ give you comments to improve the code. You can make additional changes
 and push them to the same feature branch and they will be automatically
 added to the pull request.
 
+Running Tests
+~~~~~~~~~~~~~
+
+We run many tests and checks automatically on GitHub (collectively called "CI")
+for a variety of build configurations. See :ref:`sec-runtestsuite` for how to
+run them locally. Running the full test suite can take some time, but it's a
+good idea to run at least the unit tests locally when you're making changes:
+
+.. code-block:: console
+
+    cmake --build build --target check-unit-tests
+
+Along with the automated tests, we also run things like formatters and static
+analysis in CI, which may provide further feedback (see :ref:`sec-coding-style`
+for more details). If your PR fails the format check on CI, please install the
+formatters and run them according to the next section. Usually this is just:
+
+.. code-block:: console
+
+    git clang-format next
+
+which will format just the parts of C++ files that have changed since ``next``.
+
+Formatting and Linters
+~~~~~~~~~~~~~~~~~~~~~~
+
+For frequent developers, we strongly recommend installing the formatting and
+linting tools locally and building them into your regular workflow. You can
+install the majority of our developer tools at once using `uv
+<https://docs.astral.sh/uv/>`_ from the top of your BOUT++ directory:
+
+.. code-block:: console
+
+    uv sync --only-dev --inexact
+
+This will install all the developer tools into a virtual environment (creating
+one if necessary, typically under ``.venv``). You can then activate the virtual
+environment and use the tools manually, or via integrations in your editor.
+
+We *strongly* recommend using ``uv`` to install the developer tools, as this
+will ensure that you get the *exact* versions used in CI and by other
+developers, but you could also use ``pip install --group dev`` if you wish.
+
+The quickest way to run all the formatters on a PR at once is typically:
+
+.. code-block:: console
+
+    uv tool run prek run --from-ref next
+
+This will run all our formatters on files that have changed since ``next``.
+
+Install Pre-Commit Hooks (Optional but recommended)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We also have a `prek <https://prek.j178.dev>`_ config that can run some of
+these automatically using pre-commit hooks -- that is, when you run ``git
+commit``, these tools will run and abort the commit if they change any
+files. You then just have to stage the new changes and try again.
+
+Install our developer tools with ``uv`` as above, and then install the
+pre-commit hook:
+
+.. code-block:: console
+
+    prek install
+
+That's it! ``prek`` will install the tools into their own separate virtual
+environment so they won't interfere with any you may have, and ``git`` will take
+care of running them automatically.
+
+.. _sec-coding-style:
+
 Coding Style
 ------------
 
@@ -189,6 +261,25 @@ These guidelines are intended to make code easier to read and therefore
 easier to understand. Being consistent in coding style also helps
 comprehension by reducing cognitive load.
 
+We use various tools to enforce code style and quality:
+
+- `clang-format <https://clang.llvm.org/docs/ClangFormat.html>`_ for formatting
+  of C++ code
+- `clang-tidy <https://clang.llvm.org/extra/clang-tidy/index.html>`_ for linting
+  and static analysis of C++ code
+- `ruff <https://astral.sh/ruff>`_ for formatting and linting of Python code
+- `cmake-format <https://github.com/cheshirekow/cmake_format>`_ for formatting
+  CMake files
+- `sphinx-lint <https://github.com/sphinx-contrib/sphinx-lint>`_ for linting
+  documentation pages
+
+You can install all of these tools using:
+
+.. code-block:: console
+
+    pip install -r requirements_dev.txt
+
+
 Comments
 ~~~~~~~~
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,3 +4,23 @@ requires = []
 # Defined by PEP 517:
 build-backend = "backend"
 backend-path = ["tools/pylib/_boutpp_build/"]
+
+[dependency-groups]
+dev = [
+     "cmake~=4.2",
+     "clang-format~=22.0",
+     "clang-tidy~=22.0",
+     "clangd~=22.0",
+     "clangd-tidy~=1.1",
+     "cmakelang~=0.6",
+     "prek>=0.3.5",
+     "pyyaml~=6.0",
+     "ruff~=0.15",
+     "sphinx-lint~=1.0",
+     "sync-with-uv~=0.5.0",
+]
+maint = [
+      "pygithub~=2.8",
+      "ruamel-yaml~=0.19",
+      "Unidecode~=1.3",
+]
diff --git a/requirements_dev.txt b/requirements_dev.txt
@@ -0,0 +1,6 @@
+clang-format~=22.0
+clang-tidy~=22.0
+cmakelang~=0.6
+pre-commit>=4.5.1
+ruff
+sphinx-lint~=1.0
diff --git a/uv.lock b/uv.lock
