From 8f043ce55ed098142d8e0f3567b0f8f6e2401aea Mon Sep 17 00:00:00 2001 From: bong-water-water-bong Date: Fri, 13 Nov 2026 04:51:34 -0400 Subject: [PATCH 1/2] CONTRIBUTING: point at docs/pre-pr-checks.md, which nothing linked to MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Measured: of the 45 files in `docs/`, exactly one had no inbound link from any other `.md` at `origin/main` — **`docs/pre-pr-checks.md`**, the before-you-merge page from engine#2311 that has since grown the #2341 section. A page nothing links to is a page nobody runs: the six checks in it are the ones that catch what a green tick and a careful read do not. The natural home is `CONTRIBUTING.md`, right under the five rules it operationalises, and the pointer says what the page is for rather than only where it is: none of the checks needs a device or a build, and the page also covers the one thing that is not a command — build the target that contains the file you edited, which is not necessarily the target your test links. After: 45 docs, 0 with no inbound link. Two instrument notes from finding this, both the same shape as the content of the page: - My first measurement said the orphan was `docs/oga-drafter-path.md`, and it was wrong: I ran `git grep HEAD` in the shared clone, whose checkout was behind `origin/main`, where `docs/npu.md` already links it. The measurement read a different revision than the one I named (`registration_loss_check` exists for exactly this mistake, one layer up). - `git checkout -- ` restores from the **index**, not from HEAD, so the hunk I meant to drop stayed staged until `git checkout HEAD -- `. A command whose name suggests "revert" and whose behaviour is "un-modify relative to the index" is the same family: the instrument answered a question adjacent to the one asked. --- CONTRIBUTING.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b86b8a268..75a41a5f2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -41,6 +41,11 @@ This repository exists to be reviewable. Five rules keep it that way. template that emits the notice into a generated file) and is left alone; the three such files say so in a comment. +Before you ask for a merge, run the six host-side checks in +[docs/pre-pr-checks.md](docs/pre-pr-checks.md). None of them needs a device or a build, and each answers a question that a +green CI tick and a careful read of your own diff do not. The page also covers the one thing that is not a command: build the +target that contains the file you edited, which is not necessarily the target your test links. + ## RFCs: design before code Changes that shape the engine start as an RFC in From 83755797109d76e451f8d47eb07082ca996cb107 Mon Sep 17 00:00:00 2001 From: bong-water-water-bong Date: Fri, 13 Nov 2026 05:21:05 -0400 Subject: [PATCH 2/2] Address the CHANGES at 8f043ce: name the runner, not only the page The verdict is right and the reason is the one this PR is about. `scripts/pre-pr-checks.sh` (engine#2313) runs all six and prints one line each; `CONTRIBUTING.md` told a contributor to run six commands, the page it sent them to listed six commands, and the one command that runs six was named in neither. That is a pointer that stops one step short -- the same failure as `--fix` printing its own command while a lane kept pasting a block, or `onebit_serve_syntax` existing while a page recommended the whole binary. `CONTRIBUTING.md` now says: run `scripts/pre-pr-checks.sh`, with `--base ` for the registration check and `--list` for the commands, and with the honest behaviour of the thing it names -- a check that cannot run says `skip` and why, and an unresolvable `--base` is a usage error rather than a skip. Run here: **5 green, 1 skipped** (`submodule_pin_check`: 7 submodules not initialised), which is the skip arm doing what the sentence says rather than a claim I inferred. --- CONTRIBUTING.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 75a41a5f2..19c98dc63 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -41,10 +41,12 @@ This repository exists to be reviewable. Five rules keep it that way. template that emits the notice into a generated file) and is left alone; the three such files say so in a comment. -Before you ask for a merge, run the six host-side checks in -[docs/pre-pr-checks.md](docs/pre-pr-checks.md). None of them needs a device or a build, and each answers a question that a -green CI tick and a careful read of your own diff do not. The page also covers the one thing that is not a command: build the -target that contains the file you edited, which is not necessarily the target your test links. +Before you ask for a merge, run `scripts/pre-pr-checks.sh`. It runs the six host-side checks described in +[docs/pre-pr-checks.md](docs/pre-pr-checks.md) and prints 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. None of them needs a device or a build, and each answers a question that a green CI tick and a careful read of your own +diff do not. The page also covers the one thing that is not a command: build the target that contains the file you edited, +which is not necessarily the target your test links. ## RFCs: design before code