Skip to content

docs: run the checks CI runs, and what a green one does not prove - #293

Merged
imran-siddique merged 1 commit into
agentrust-io:mainfrom
lywinged:contributing-read-the-repair
Sep 5, 2026
Merged

docs: run the checks CI runs, and what a green one does not prove#293
imran-siddique merged 1 commit into
agentrust-io:mainfrom
lywinged:contributing-read-the-repair

Conversation

@lywinged

@lywinged lywinged commented Sep 5, 2026

Copy link
Copy Markdown
Collaborator

What this changes

CONTRIBUTING.md only. 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.yml runs ruff check src tests scripts; the file said ruff check src tests. ci.yml runs python tools/check_dashes.py as 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 to pytest; 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 to in its place, and the checker passes on 1to3 where 1 to 3 was 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.py already 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

  • Editorial (typo, link fix, clarification: no normative effect)

Spec section

None. No normative text, no schema change.

Checklist

  • DCO sign-off on all commits (git commit -s)
  • CHANGELOG.md updated (for any normative change): not applicable, and recent docs-only changes to this file carry no entry
  • Breaking changes marked with <!-- CHANGED: #NNN: description --> in spec text: not applicable
  • Backward compatibility statement included (for breaking changes): not applicable

Tool-assisted: the comparison against ci.yml and this write-up.

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
@lywinged
lywinged requested a review from a team as a code owner September 5, 2026 12:56
@github-actions

github-actions Bot commented Sep 5, 2026

Copy link
Copy Markdown
Contributor

Contributor Check: UNKNOWN

Check Result
Profile UNKNOWN
Credential LOW
Overall UNKNOWN

Automated check by AgenTrust Contributor Check.

@github-actions github-actions Bot added the needs-review:UNKNOWN Contributor check flagged UNKNOWN risk label Sep 5, 2026

@imran-siddique imran-siddique left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@imran-siddique
imran-siddique merged commit 1042273 into agentrust-io:main Sep 5, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs-review:UNKNOWN Contributor check flagged UNKNOWN risk

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants