From 2e30059028a8df808fd22fe13e9d6a9c574f2cf9 Mon Sep 17 00:00:00 2001
From: Rick van Hattem <wolph@wol.ph>
Date: Sun, 20 Sep 2026 00:15:57 +0200
Subject: [PATCH] Apply automatic Ruff fixes to pull requests

---
 .github/workflows/autofix.yml | 36 +++++++++++++++++++++++++++++++++++
 .github/workflows/main.yml    |  6 ++++++
 CONTRIBUTING.rst              | 12 ++++++++++++
 tox.ini                       | 11 +++++++++++
 4 files changed, 65 insertions(+)
 create mode 100644 .github/workflows/autofix.yml

diff --git a/.github/workflows/autofix.yml b/.github/workflows/autofix.yml
new file mode 100644
index 00000000..7c4409f7
--- /dev/null
+++ b/.github/workflows/autofix.yml
@@ -0,0 +1,36 @@
+# Ruff rewrites quote styles and capitalises docstrings without any help
+# from a person, so a contributor should never have to. This hands those
+# fixes to the autofix.ci app, which commits them to the pull request
+# branch, forks included. The existing lint gate still reports any
+# findings that ruff cannot fix.
+#
+# The filename and the workflow name are both fixed by autofix.ci, which
+# uses them to identify the workflow it trusts. Renaming either one stops
+# the app from accepting the patch.
+name: autofix.ci # needed to securely identify the workflow
+
+on:
+  pull_request:
+  push:
+    branches: [develop, master]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  autofix:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: '3.13'
+      - run: uvx --with tox-uv tox -e ruff-fix
+      - uses: autofix-ci/action@c5b2d67aa2274e7b5a18224e8171550871fc7e4a # v1.3.4
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 71cbdf9c..10025e64 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -89,7 +89,13 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip tox
+      - name: Apply Ruff fixes to pull requests
+        if: github.event_name == 'pull_request' && matrix.tox-env == 'ruff'
+        run: tox -e ruff-fix
       - name: Test with tox
+        env:
+          RUFF_OUTPUT_FORMAT: >-
+            ${{ github.event_name == 'pull_request' && 'github' || 'full' }}
         # Step-level continue-on-error keeps the job green for
         # experimental (pre-release Python) environments while still
         # showing the failing step in the logs
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 5477d533..a7227ab1 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -161,3 +161,15 @@ To run a subset of tests::
     $ uv run pytest tests/some_test.py
 
 .. _git-flow-avh: https://github.com/petervanderdoes/gitflow
+
+Automatic formatting
+--------------------
+
+Pull requests apply Ruff fixes before the lint check. With the autofix.ci
+app installed for this repository, those fixes are committed to the pull
+request branch, including forks. Findings Ruff cannot fix still fail CI.
+Push builds check the committed files without applying fixes.
+
+Apply the same fixes locally with::
+
+    uvx --with tox-uv tox -e ruff-fix
diff --git a/tox.ini b/tox.ini
index ae273629..8168f0d6 100644
--- a/tox.ini
+++ b/tox.ini
@@ -82,6 +82,7 @@ commands =
     sphinx-build -b linkcheck -d docs/_build/doctrees docs docs/_build/linkcheck
 
 [testenv:ruff]
+pass_env = RUFF_OUTPUT_FORMAT
 commands =
     ruff check
     ruff format --check
@@ -93,3 +94,13 @@ changedir = {toxinidir}
 commands = codespell .
 deps = codespell
 skip_install = true
+
+
+[testenv:ruff-fix]
+labels = fix
+description = Apply the available Ruff fixes
+commands =
+    ruff check --fix --exit-zero
+    ruff format
+deps = ruff
+skip_install = true