From 4f46197d84a1c93e3480003ce7e4fd696619e185 Mon Sep 17 00:00:00 2001 From: Louielunz <48041247+lywinged@users.noreply.github.com> Date: Sat, 5 Sep 2026 12:47:59 +0000 Subject: [PATCH] docs: run the checks CI runs, and what a green one does not prove Two of the five steps CI runs were not in the command block here. `ruff` runs over `scripts` in CI and over `src tests` in this file, and `tools/check_dashes.py` is a CI step with no local counterpart at all. A contributor following this file meets both for the first time as a red build, which is the worst moment to meet a style rule, because the cheapest way out is a character edit that satisfies the checker. The paragraph that follows says why that way out is a trap. A ban on a character cannot see the shape of its replacement: take an en dash out of a range, put a bare `to` in, and the checker passes on `1to3`. The general form is that the check you just fixed is the one instrument guaranteed not to see what your fix introduced, so it cannot be the evidence that your fix is right. No normative text and no schema change. Recent docs-only changes to this file carry no CHANGELOG entry, so this one does not either. Signed-off-by: Louielunz <48041247+lywinged@users.noreply.github.com> Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01TGTKY8Fut5trnDKm8TReTa --- CONTRIBUTING.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4b36fef..6878b5b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,7 +9,8 @@ Install the development dependencies and run the suite from the repository root: ```bash pip install -e ".[dev]" pytest -ruff check src tests +ruff check src tests scripts +python tools/check_dashes.py mypy src/agentrust_trace ``` @@ -18,6 +19,16 @@ wheel installed elsewhere in the environment must not shadow the code under test; a regression test fails with the resolved import path if that guarantee is lost. +A check turning green is not a review of the edit that turned it green. Each of +these was built to see one thing, and none of them sees what your repair +introduced. `tools/check_dashes.py` bans four characters and prints the form to +use instead, and it cannot tell whether you used that form. Take an en dash out +of a range, put a bare `to` in its place, and you have `1to3` where `1 to 3` was +meant, with the check passing: a ban on a character cannot see the shape of the +replacement. Read the changed line in the shape a reader meets it, rendered +rather than as source, and run something that could have caught the new mistake. +The check you just fixed is not that something. + ## Using AI to contribute Use agents. A lot of this was built with them and saying otherwise would be dishonest.