From 012e5bcf6df6fb9a111c067bd5d0a8ef109796b6 Mon Sep 17 00:00:00 2001 From: bong-water-water-bong Date: Thu, 12 Nov 2026 18:21:20 -0400 Subject: [PATCH] docs: the checks to run before asking for a merge, in one place Six host-side commands that answer questions `mergeable=true`, a green CI tick and a careful read of your own diff do not, plus the two that exist for a specific moment (conflict_triage before resolving a many-file merge, hrx_f16_narrowing when the change could touch f32-to-f16 narrowing). The one worth writing down is registration_loss_check: a PR's diff is computed against its MERGE BASE, so when main moves under you every row another lane landed shows in your diff as a removal, and a resolution that takes your side deletes it. Measured three times on 2026-11-11/12 -- main-whisper-tool (#2183) five commits behind with 48 of main's 429 registrations removed, two merged the same day; #2091's naive resolution dropping eight policy_verdict references; and one of this lane's own branches carrying an already-merged commit. The page states the three verdicts the tool distinguishes (deleted / stale+conflicting / stale+clean) so its output is actionable rather than alarming. And it records which of these are NOT CI rows and why: registration_loss_check and conflict_triage compare two revisions, and a build only ever has one, so the merge-base question can only be asked before the merge. Their self-tests are ctest rows, so a check that stops working still turns the build red. The page's own first check caught its author: docs/ carries an HTML-comment notice and the draft had none, so `tools/copyright.py --check` returned 1 on the file that documents it. Fixed with the tool's own --fix, and every command in the table now verified to run as written from the repo root. --- docs/pre-pr-checks.md | 62 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 docs/pre-pr-checks.md diff --git a/docs/pre-pr-checks.md b/docs/pre-pr-checks.md new file mode 100644 index 000000000..b8c5126bf --- /dev/null +++ b/docs/pre-pr-checks.md @@ -0,0 +1,62 @@ + +# 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 +`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. + +| command | red means | +|---|---| +| `python3 tools/copyright.py --check` | a file has no notice, or has two | +| `python3 tools/ci/tests_referenced_check.py` | a test, tool self-test or python test exists that nothing runs | +| `python3 tools/ci/ci_targets_check.py --check` | a CI row names a target or path that does not exist | +| `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 | + +Two more, for the moments they are for: + +| command | when | +|---|---| +| `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 | + +## Why the merge-base one is not the same as "it merges" + +A PR's diff is computed against its **merge base**. If `main` moved under you, every row another lane landed shows in your +diff as a removal, and a resolution that takes your side deletes it. Measured three times on 2026-11-11/12: `main-whisper-tool` +(#2183) was five commits behind and its diff removed 48 of `main`'s 429 registrations, two rows of which had been merged the +same day; #2091's naive resolution would have dropped eight `policy_verdict` references; and one of this lane's own branches +carried an already-merged commit for the same reason. + +`registration_loss_check` separates the three states, so its message is actionable rather than alarming: + +- **rows deleted by your branch** (present at the merge base, absent at your head) — a merge honours the deletion; say in the + commit message that you meant it; +- **stale and conflicting** — the risky combination: the conflict sits in a file full of other lanes' rows, and taking your + side drops them; rebase and keep every row `main` has; +- **stale and clean** — behind, not destructive: the merge keeps `main`'s rows. Rebase when convenient. + +## These are not CI rows + +Every check above runs in CI except `registration_loss_check` and `conflict_triage`, which compare two revisions — a build only +ever has one. That is why they are here: the merge-base question can only be asked before the merge. + +The self-tests of all of these *are* ctest rows (`tools/ci/*.py --self-test`), so a check that stops working turns the build red +even though its own verdict is a manual one.