Skip to content

pre-pr-checks: the page-nobody-links-to check, as a row and as the story behind it - #2351

Merged
bong-water-water-bong merged 1 commit into
mainfrom
pkg/prepr-orphan-row
Nov 13, 2026
Merged

bong-water-water-bong merged 1 commit into
mainfrom
pkg/prepr-orphan-row

Conversation

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator

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.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.

…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.
@github-actions

Copy link
Copy Markdown

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪
🧪 No relevant tests
🔒 No security concerns identified
⚡ Recommended focus areas for review

Documentation Inconsistency

The new command added to check for orphaned documentation pages uses a placeholder <your new page> which is not a valid shell command. This could mislead users into thinking it's a valid command, when in fact it's meant to be replaced with an actual page name. The command should be updated to reflect a proper usage example or a clearer instruction.

| `git grep -l -F "$(basename <your new page>)" -- '*.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 |
Missing Context for Command

The explanation for the orphan page check command lacks sufficient context. It does not clearly explain what the command does or how to interpret its output. A more detailed explanation would help users understand the purpose and usage of the command.

git grep -l -F "$(basename docs/your-new-page.md)" -- '*.md'

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

VERDICT: READY a443f4f

The lesson is the right one and it is stated with its own evidence: docs/pre-pr-checks.md had no inbound link from any .md for two hours after it merged — "reachable only by knowing its name". Turning that into a seventh pre-merge command is exactly the kind of self-correction a page like this should carry, and the command is right:

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. 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 (CONTRIBUTING.md, under the rules the page operationalises) rather than from an index nobody opens is the part that makes the link useful rather than merely present.

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 tools/ci/ (the --help check in #2339 and the syntax checks are the same shape) that greps every docs/*.md for an inbound link and fails on an orphan would close the class; this documents it. Both are worth having, but only one of them runs when nobody remembers.

A smaller point about the command itself: basename matches the file name, so a page linked as pre-pr-checks.md or ./docs/pre-pr-checks.md both hit, which is the right level of tolerance — but it would also hit a link to a different file that happens to share the basename. With flat docs/ that is not a problem today; if subdirectories arrive, matching the path rather than the basename would be stricter.

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
bong-water-water-bong merged commit 8817d4b into main Nov 13, 2026
9 checks passed
@bong-water-water-bong
bong-water-water-bong deleted the pkg/prepr-orphan-row branch November 13, 2026 09:20

@bong-water-water-bong bong-water-water-bong left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 bong-water-water-bong left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

bong-water-water-bong added a commit that referenced this pull request Nov 13, 2026
…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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant