docs(contributing): rename Manual Verification to Verification, make it a merge gate

The old name implied the list was only for by-hand steps, which sat badly
with the fact that most entries in practice are programmatic — the test
suite, `fish_indent`, `docs/verify-manual.py`, CI. Dropping "Manual" lets
one list carry both kinds, and gives the checkbox state real meaning:

- **Checked** — verified, whether it ran programmatically or the author
  performed it by hand.
- **Unchecked** — an outstanding manual check the reviewer still has to
  perform. Left visible rather than dropped.
- **The list is the merge gate.** A PR isn't merged until every box is
  checked; added as an explicit rule under Branching & Pull Requests
  alongside the other merge rules.

Because unchecked boxes now block the merge, the guidance also states that
only resolvable checks belong here — one nobody can run would block the PR
indefinitely. Genuinely unverifiable caveats and assumptions go in
`## Notes`, which already existed in the optional-sections list.

Incidentally realigns with PRs 121-122, which had already shortened the
heading to `## Verification`; that part of the recent drift was right.
This commit is contained in:
2026-08-31 22:35:30 -04:00
parent 2f49960149
commit ea8b13b38a
2 changed files with 37 additions and 14 deletions
+20 -8
View File
@@ -8,7 +8,7 @@
Keep the two headings below, in this order, and delete these comments.
Optional sections may be added between them (see the note above
"Manual Verification").
"Verification").
-->
## Summary
@@ -28,8 +28,8 @@
site build only.
If this PR resolves a tracked issue, close it with a trailing line at the
end of this section — not at the very bottom, since Manual Verification
is always last:
end of this section — not at the very bottom, since Verification is
always last:
Closes #42
@@ -64,13 +64,25 @@
reasonably ask why the obvious approach was rejected.
-->
## Manual Verification
## Verification
<!--
Reproducible steps a reviewer can run themselves, as a checkbox list.
Run them first, then check each box — an unchecked box means it was NOT
verified, and should be called out as such rather than left silently
blank. This section is always last.
Every check this change needs, as a checkbox list. Always the last
section.
A CHECKED box means verified — either it ran programmatically (test
suite, linter, docs verifier, CI) or the author performed it by hand and
confirmed the result. Check these off before opening the PR.
An UNCHECKED box is an outstanding manual check the reviewer still has to
perform. Leave anything you could not verify yourself unchecked rather
than dropping it, so it stays visible.
**This list is the merge gate: the PR does not merge until every box is
checked.** So only put things here that can actually be resolved — a
check nobody is able to run blocks the PR forever. Genuinely unverifiable
caveats, assumptions, and known limitations belong in a `## Notes`
section instead, where they inform the review without gating it.
- One check per line, imperative, with the exact command in backticks
and the expected result stated.