Files
ersatztv/docs/decisions/records/ci/python-lint-ruff-config-committed.md
T
timothy 18b2a46beb feat(780): commit a ruff config and enforce it in CI
Python lint here was a property of the operator's laptop, not of the repo: the
global instructions say to run `ruff check`/`ruff format --check`/`pyright`, no
workflow or hook ran any of them, and with no committed config ruff fell back to
whichever `~/.config/ruff/ruff.toml` the machine happened to have. A second
machine lints this repo differently, or not at all — Family E in
docs/defect-shapes-773.md, in our own toolchain.

Option 1 from the issue:

- `ruff.toml` at the root (the operator's global settings, pinned here — that is
  what the tree was de-facto written against, so adopting it cost a mechanical
  reformat rather than a rewrite).
- The `script-tests` job installs a PINNED `ruff==0.12.11` and runs
  `ruff check .` + `ruff format --check .` before pytest, so a style red arrives
  in seconds instead of after the four-minute suite. The pin is the second half
  of the fix: an unpinned install re-introduces the same divergence one layer up.
  Renamed the job to `Script lint and tests (ruff + pytest)` so a lint red is not
  triaged under a name that says pytest.
- Tree made clean: 72 errors and 20 files needing reformatting. Everything fixed
  except two config-level exemptions with reasons in the config (`S101`, `S105`
  under `scripts/tests/**` — the stub credentials that fire `S105` have no true
  positive anywhere in the tree) and two per-site `# noqa`s that carry their
  reason inline.

`pyright` stays ungated: its only findings are `reportMissingImports` for
`etv_client` in scripts/scripted-schedules/entrypoint.py, resolvable only in that
script's deploy environment, and gating it would put a node toolchain on the
git-only `small` lane to find nothing.

Population is what `ruff check .` discovers from the root, so a new `.py`
anywhere is covered without the job enumerating anything.

Docs: new record `ci.python-lint-ruff-config-committed`, cross-ref from
`ci.script-tests-job`, `docs/ci-cd.md` script-tests section, and
`docs/defect-shapes-773.md` §5.2 marked resolved with the measured numbers.

Refs: #780
Decisions-Edit: yes
2026-08-21 22:47:22 +02:00

3.2 KiB

key, title, status, since, supersedes, superseded-by, rule, signals, mechanics
key title status since supersedes superseded-by rule signals mechanics
ci.python-lint-ruff-config-committed 2026-08-21 — Python lint is a committed ruff.toml enforced in CI, not the operator machine's global config (#780) active 2026-08-21 none none The repo commits `ruff.toml` and the `script-tests` job runs `ruff check .` + `ruff format --check .` against a PINNED ruff. Never rely on `~/.config/ruff/ruff.toml`, and never add a lint rule to the config without making the tree clean against it in the same PR. ruff · pyright · python lint · `ruff format --check` · lint passes on my machine but not yours · no repo lint config · S105 on a test stub credential · paths: `ruff.toml`, `.gitea/workflows/pr-checks.yml` · issues: #780, #773, #648, #512 Config at repo root; the job pins `ruff==0.12.11` via pip and runs both commands before pytest so a style red arrives in seconds. Bumping the pin is a deliberate PR because a new ruff release adds rules. Population is whatever `ruff check .` discovers from the root, so a new `.py` anywhere is covered without enumeration.

The global instructions tell every session to run ruff check, ruff format --check and pyright after touching Python. Before this, the repo enforced none of them and committed no config, so ruff fell back to whichever ~/.config/ruff/ruff.toml the operator's machine happened to have — a second machine lints this repo differently, or not at all. That is the same shape as #643/#647/#648 (a shell gate whose behaviour was a function of an untested interpreter version) and #512 (a test that passed on a fast laptop and flaked on a starved CI VM): the verdict was a property of the environment rather than of the repo.

The committed config is the operator's global one, pinned here — that is what the tree was de-facto written against, so adopting it cost a mechanical reformat rather than a rewrite.

Two exemptions are in the config, not in people's heads. scripts/tests/** is exempt from S101 (the suite asserts) and from S105: those tests hand the real hooks deliberately fake credentials (env["ETV_GITEA_TOKEN"] = "stub"), which fires the hardcoded-password rule eight times with no true positive anywhere in the tree. Everything else that fired was fixed, not ignored. A per-site # noqa carries its reason inline — the two that survive are a percent-format template whose payload contains literal braces, and one-line JSON fixtures that cannot be split without changing the payload.

pyright is deliberately NOT gated. Its only findings here are reportMissingImports for etv_client in scripts/scripted-schedules/entrypoint.py, resolvable only inside that script's deploy environment. Gating it would put a node toolchain on the git-only small lane to find nothing. Revisit when this repo grows a typed Python surface — the reason is the cost/finding ratio today, not a judgement that type checking does not belong.

The pin is the second half of the fix. An unpinned pip install ruff re-introduces exactly the divergence the config closes, one layer up: the verdict becomes a function of when the job ran. Same argument as the jq pin in the same job (ci.jq-version-contract), and the same consequence — a bump is a PR someone reads.