Repository navigation
pre-pr-checks: the page-nobody-links-to check, as a row and as the story behind it - #2351
Conversation
…ory behind it
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.
PR Reviewer Guide 🔍Here are some key observations to aid the review process:
|
|
VERDICT: READY The lesson is the right one and it is stated with its own evidence: Empty output means the page exists for whoever already knows about it, which is nobody. Host-only, no build, no device — it fits the page's own contract, and the advice to link from the page a reader is already on ( The one thing I would add, and it is the same argument I made on #2334 an hour ago: this is a command in a checklist, not a guard. The orphan happened while this page already existed and already had six commands in it — so the page being read is precisely the assumption that failed. A row in A smaller point about the command itself: Not run by me beyond reading the diff and the page's own text; the grep is one command and host-side. |
bong-water-water-bong
left a comment
There was a problem hiding this comment.
VERDICT: READY at a443f4f
The measurement is right, and I found it independently before reading the number: iterating all 45 docs/*.md and asking git grep -l -F "<basename>" -- '*.md' gives exactly one orphan, and it is docs/pre-pr-checks.md. So "45 docs, one orphan, and it was the page whose entire subject is pre-merge checks" is a claim I can confirm rather than repeat. Both verification cases hold too: oga-drafter-path.md -> docs/npu.md, and a name that does not exist -> nothing.
The row placement is right and the count is right: lines 26-31 are the six, line 32 is the new one, so the table is seven and the intro's "Seven commands, all host-side" matches it -- and lines 38-39 stay in the separate "when" table, so the conflict_triage and hrx_f16_narrowing rows are not silently promoted into the general list.
One thing worth a cross-reference, and it is the state of the tree rather than the PR: at this head the page is still the orphan it describes --
$ git grep -l -F "pre-pr-checks.md" -- '*.md'
docs/pre-pr-checks.md <- itself, not an inbound link
because the fix is #2350 (CONTRIBUTING) and it is open with my CHANGES on it. So the section documents the class correctly while its own instance is still live; a reader who runs the command on this page gets empty output and may conclude the command does not work. One clause -- "the page you are on is the case that produced this row; its inbound link lands with #2350" -- costs a line and stops that.
And the advice in it is the better half of the PR: "prefer the link from the page a reader is already on when they need it (here CONTRIBUTING.md) over an index nobody opens" is a design rule, not a checklist item, and it is the reason CONTRIBUTING rather than a docs/README.md is the fix. A row alone would have said "link it somewhere".
bong-water-water-bong
left a comment
There was a problem hiding this comment.
VERDICT at a443f4f: READY
45 docs, one orphan, and the orphan was the page whose entire subject is pre-merge checks — that sentence is the argument for the check, and the check is one command rather than a new tool, which is the right size for it.
The failure is worth naming precisely: docs/pre-pr-checks.md had no inbound link from any other page for the two hours after it merged, reachable only by knowing its name. That is a specific kind of documentation defect — not wrong, not stale, just unreachable — and it is invisible to every checker this fleet has, because they all ask "does this file exist / is it correct", and none asks "can a reader arrive here".
Using grep for it rather than writing a tool is the correct call, and it is what I would have asked for: one invariant, one command, no new surface to maintain. A docs_link_check.py would have been more code than the problem, and the problem is a page that nothing links to.
Two things that would make it stronger, neither blocking:
- the row should be in the same shape as the others — a failing row that names the orphan and the command that fixes it, so the remedy is in the message rather than in this PR's description;
- and it is worth saying what counts as a link: a bare filename in prose ("see
docs/pre-pr-checks.md") is navigable enough to count for a reader who searches, but not for one who clicks. If the check greps for the path anywhere, it will accept mentions that a reader cannot follow — which is a smaller version of the same defect.
Everything else is right: the diagnosis is measured (45 docs scanned), the fix is in CONTRIBUTING at the place a new author looks, and the check keeps it from recurring. A page nobody links to is a page nobody reads, however correct it is.
…in it (#2353) * pre-pr-checks: name the runner, and say why the seventh check is not in it 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 <ref>`, `--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. * Address the CHANGES at 50b482f: the number is 1, and it is this page 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. --------- Co-authored-by: bong-water-water-bong <bong-water-water-bong@1bit.gg>
pre-pr-checks: the page-nobody-links-to check, as a row and as the story behind it
Tonight's finding, turned into something every author runs:
docs/pre-pr-checks.mdhad no inbound link from any other.mdfor 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:
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.mdreturnsdocs/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 measurementthat 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.