docs: run the checks CI runs, and what a green one does not prove - #293
Merged
imran-siddique merged 1 commit intoSep 5, 2026
Merged
Conversation
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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TGTKY8Fut5trnDKm8TReTa
Contributor
|
❔ Contributor Check: UNKNOWN
Automated check by AgenTrust Contributor Check. |
imran-siddique
approved these changes
Sep 5, 2026
imran-siddique
left a comment
Member
There was a problem hiding this comment.
Checked the full CONTRIBUTING.md diff against the current CI workflow: the added scripts path in Ruff and the dash-check command match the workflow, while pytest keeps its documented local form without CI's coverage flags. This is an editorial contribution with a signed-off commit. The current head has green Python 3.11/3.12 and CodeQL results and no unresolved review threads.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this changes
CONTRIBUTING.mdonly. The command block under "Running the reference-library checks" now lists the checks CI runs, and a paragraph after it says what a passing check does not establish.Two of CI's steps were not reachable from this file.
ci.ymlrunsruff check src tests scripts; the file saidruff check src tests.ci.ymlrunspython tools/check_dashes.pyas a step of its own; the file did not mention it. A contributor following this file meets both for the first time as a red build. The five commands now match CI one for one, except that CI adds coverage flags topytest; the block keeps the bare form it already carried.The paragraph is there because of what a red build invites. A ban on a character cannot see the shape of its replacement: take an en dash out of a range, put a bare
toin its place, and the checker passes on1to3where1 to 3was meant. 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.tools/check_dashes.pyalready prints the intended form for each character it bans, which is advice rather than an instrument, and nothing verifies that the repair used it.Type of change
Spec section
None. No normative text, no schema change.
Checklist
git commit -s)CHANGELOG.mdupdated (for any normative change): not applicable, and recent docs-only changes to this file carry no entry<!-- CHANGED: #NNN: description -->in spec text: not applicableTool-assisted: the comparison against
ci.ymland this write-up.