diff --git a/docs/pre-pr-checks.md b/docs/pre-pr-checks.md index 280aeb4ac..447c6be97 100644 --- a/docs/pre-pr-checks.md +++ b/docs/pre-pr-checks.md @@ -21,6 +21,11 @@ Seven commands, all host-side, none needing a device or a build. Every one of th Run them from the repository root on the branch you are about to hand over. +**`scripts/pre-pr-checks.sh` runs the first six**, one line each (`--base ` for the registration check, `--list` to see the +commands; a check that cannot run says `skip` and why, and an unresolvable `--base` is a usage error rather than a skip). The +seventh is an **author's check**, true or false exactly once — when you add a page — so it is not in the runner, and the section +below says why. + | command | red means | |---|---| | `python3 tools/copyright.py --check` | a file has no notice, or has two | @@ -46,7 +51,13 @@ open the PR, grep for your own page's name and see someone else's file come back git grep -l -F "$(basename docs/your-new-page.md)" -- '*.md' -Empty output means the page exists for whoever already knows about it, which is nobody. Prefer the link from the page a reader is +Empty output means the page exists for whoever already knows about it, which is nobody. + +**Why this one is not in `scripts/pre-pr-checks.sh`**: that runner is a loop over `python3` tools that carry their own self-tests, +and a repo-wide form of this check is a new tool for an invariant that measures **1 today — this page** — and 0 once engine#2350 +adds its inbound link. That is the strongest argument for it being an author's step rather than a gate: **the number it reports is a +property of the tree at that moment, not of your change** — it flips from 1 to 0 when a *different* PR merges, which is not a +statement about anything the author did. What the author's own command answers is: does the page I am adding have a way in. Prefer the link from the page a reader is already on when they need yours — here `CONTRIBUTING.md`, under the rules the page operationalises — rather than from an index nobody opens.