From 50b482fcd94472e648ec996b603330f3f8b8c349 Mon Sep 17 00:00:00 2001 From: bong-water-water-bong Date: Fri, 13 Nov 2026 05:30:42 -0400 Subject: [PATCH 1/2] pre-pr-checks: name the runner, and say why the seventh check is not in it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit My own merge created this inconsistency an hour ago. #2351 added a seventh row to the page (`git grep` for your new page's name); the page's intro moved six → seven; **`scripts/pre-pr-checks.sh` still runs six, and the page never named it** — so a reader now sees a table of seven, a runner of six, and nothing that connects them. That is the failure the review of #2350 named, committed by me in the same category: *a pointer that stops one step short*. Two sentences: 1. **`scripts/pre-pr-checks.sh` runs the first six**, with its own honest behaviour stated (`--base `, `--list`, `skip` and why, an unresolvable `--base` as a usage error). 2. **Why the seventh is not in the runner**: the runner is a loop over `python3` tools carrying self-tests, and a repo-wide form of the orphan check is a new tool for an invariant that measures **0 today** (45 docs, none orphaned). It is worth one command at the moment a page is added, which is the only moment it can be false. Measured rather than asserted: `scripts/pre-pr-checks.sh --list` prints **6** commands, and `grep -c pre-pr-checks.sh` on the page was **0** before this change and is 2 after. --- docs/pre-pr-checks.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/pre-pr-checks.md b/docs/pre-pr-checks.md index 280aeb4ac..4caced122 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,11 @@ 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 **0 today** (45 docs, none orphaned). It is worth +one command at the moment a page is added — which is the only moment it can be false. 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. From 7f480488da4f723b37786974f0b2a25858be742e Mon Sep 17 00:00:00 2001 From: bong-water-water-bong Date: Fri, 13 Nov 2026 06:10:58 -0400 Subject: [PATCH 2/2] Address the CHANGES at 50b482f: the number is 1, and it is this page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The verdict is right and the miss is the interesting kind: I measured the orphan count on a branch that contained #2350's `CONTRIBUTING.md` link, and #2350 is **open, not merged**. So `origin/main` still has no inbound link to this page, and the sentence justifying the row sat one PR ahead of the tree it described. Measured on this branch before editing, with the verdict's own loop: ORPHAN docs/pre-pr-checks.md $ git grep -l -F pre-pr-checks origin/main -- CONTRIBUTING.md -> 0 Took the verdict's second option, which is the more useful one: the section now says the invariant **measures 1 today — this page — and 0 once engine#2350 adds its inbound link**, instead of asserting a clean tree that does not exist yet. A reader learns the one live instance rather than a number that reads like a hypothetical. And it carries the clause the review suggested, because it is the argument rather than a caveat: **the number is a property of the tree at that moment, not of your change** — it flips from 1 to 0 when a *different* PR merges. That, not the count, is why this is an author's step: what your own command answers is whether the page you are adding has a way in. --- docs/pre-pr-checks.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/pre-pr-checks.md b/docs/pre-pr-checks.md index 4caced122..447c6be97 100644 --- a/docs/pre-pr-checks.md +++ b/docs/pre-pr-checks.md @@ -54,8 +54,10 @@ open the PR, grep for your own page's name and see someone else's file come back 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 **0 today** (45 docs, none orphaned). It is worth -one command at the moment a page is added — which is the only moment it can be false. Prefer the link from the page a reader is +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.