From a443f4f4e67265d85bca9d5999092429d1244024 Mon Sep 17 00:00:00 2001 From: bong-water-water-bong Date: Fri, 13 Nov 2026 05:01:06 -0400 Subject: [PATCH] pre-pr-checks: the page-nobody-links-to check, as a row and as the story behind it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tonight's finding, turned into something every author runs: `docs/pre-pr-checks.md` had **no inbound link from any other `.md`** for the two hours after it merged (engine#2311) and was reachable only by knowing its name. 45 docs, one orphan, and it was the page whose entire subject is pre-merge checks. The check is one command, no new tool: 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. Verified both ways before writing it down: `oga-drafter-path.md` returns `docs/npu.md`, and a name that does not exist returns nothing. Two things the section says that a bare row could not: prefer the link from the page a reader is already on when they need yours (here `CONTRIBUTING.md`, under the rules this page operationalises; engine#2350) over an index nobody opens, and the measurement that produced the row — 45 docs, one orphan — so the next reader knows this is not a hypothetical. Table count in the intro moves six → seven with it. --- docs/pre-pr-checks.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/pre-pr-checks.md b/docs/pre-pr-checks.md index f52058e0a..280aeb4ac 100644 --- a/docs/pre-pr-checks.md +++ b/docs/pre-pr-checks.md @@ -16,7 +16,7 @@ limitations under the License. --> # Before you ask for a merge -Six commands, all host-side, none needing a device or a build. Every one of them answers a question that +Seven commands, all host-side, none needing a device or a build. Every one of them answers a question that `mergeable=true`, a green CI tick and a careful read of your own diff do not. Run them from the repository root on the branch you are about to hand over. @@ -29,6 +29,7 @@ Run them from the repository root on the branch you are about to hand over. | `python3 tools/ci/registration_loss_check.py --check --base origin/main` | your branch would drop rows `main` has | | `python3 tools/ci/tmp_path_check.py --check` | a new `/tmp` or `/dev/shm` path, where builds and dumps belong under `~/wt` or `~/.cache/scratch-*` | | `python3 tools/ci/submodule_pin_check.py --check` | a submodule's checkout is not the commit the tree pins | +| `git grep -l -F "$(basename )" -- '*.md'` | nothing links to the page you just added — measured tonight: 45 docs, one with no inbound link, and it was the page whose whole subject is pre-merge checks | Two more, for the moments they are for: @@ -37,6 +38,18 @@ Two more, for the moments they are for: | `python3 tools/ci/conflict_triage.py . ` | before resolving a merge with many conflicted files: it classifies them by kind (content, add/add, mod/del, rename) from the index, which text tools cannot see in a file whose conflict has no markers | | `python3 tools/ci/hrx_f16_narrowing.py --check --root ` | when the change could touch f32→f16 narrowing; it lists every body that narrows | +## A page nothing links to is a page nobody runs + +`docs/pre-pr-checks.md` had no inbound link from any other `.md` for two hours after it merged: it was reachable only by knowing +its name. A new page is a claim that someone should read it, and the only mechanical half of that claim is a link — so before you +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 +already on when they need yours — here `CONTRIBUTING.md`, under the rules the page operationalises — rather than from an index +nobody opens. + ## A private pin (`config/*.config`) is the one bump CI cannot check Two of these files pin a **private** repository; they are the ones whose bumps need evidence: