From ea8b13b38a4e4103251bc73553f1708a2ca03a40 Mon Sep 17 00:00:00 2001
From: Rootiest <chris@rootiest.com>
Date: Mon, 31 Aug 2026 22:35:30 -0400
Subject: [PATCH] docs(contributing): rename Manual Verification to
 Verification, make it a merge gate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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.
---
 .github/PULL_REQUEST_TEMPLATE.md | 28 ++++++++++++++++++++--------
 CONTRIBUTING.md                  | 23 +++++++++++++++++------
 2 files changed, 37 insertions(+), 14 deletions(-)

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 8c7f886..87fad7b 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -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.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0e3a3dd..586bd53 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -48,6 +48,9 @@ assumes you *do* have push access (maintainers, regular contributors).
   branching doesn't touch the working tree.)
 - **Merge target is `main`, via PR.** Contributors open the PR; the repo
   owner merges it. Don't merge your own PR.
+- **Don't merge until the `## Verification` checklist is fully checked.**
+  Unchecked boxes are outstanding manual checks, not decoration. See
+  [Pull request descriptions](#pull-request-descriptions) below.
 - **Keep feature branches focused.** If you stumble onto something unrelated
   to your current task while working (a pre-existing bug, a stray cleanup),
   don't fold it into the same commit or PR. Handle it with one of these,
@@ -77,15 +80,23 @@ description box when you open a PR. Every PR carries, in this order:
   `Scope note`, `Opinionated guard (C1-C6)`), and skip them entirely for a
   straightforward change. A breaking change (title ending in `!` before
   the colon) must include `## ⚠️ Breaking Change` with the migration path.
-- **`## Manual Verification`** — always last. Reproducible steps as a
-  checkbox list, each with the exact command and its expected result. Run
-  them before opening the PR and check the boxes; a box left unchecked
-  means that step was *not* verified, so say so explicitly rather than
-  leaving it silently blank.
+- **`## Verification`** — always last. Every check this change needs, as a
+  checkbox list, each with the exact command and its expected result.
+  A **checked** box means verified, whether programmatically (test suite,
+  linter, docs verifier, CI) or by hand; check those off before opening the
+  PR. An **unchecked** box is an outstanding manual check the reviewer
+  still has to perform — leave anything you couldn't verify yourself
+  unchecked rather than dropping it.
+
+  **This list is the merge gate: a PR isn't merged until every box is
+  checked.** Only list checks that can actually be resolved — one nobody
+  can run blocks the PR indefinitely. Put genuinely unverifiable caveats,
+  assumptions, and known limitations in `## Notes` instead, where they
+  inform the review without gating it.
 
 When a PR resolves a tracked issue, close it with a trailing `Closes #42`
 line at the end of `## Summary` — not at the very bottom of the body, since
-`## Manual Verification` is always last. `Fixes #N` and `Resolves #N` behave
+`## Verification` is always last. `Fixes #N` and `Resolves #N` behave
 identically. Repeat the keyword for each issue (`Closes #42, closes #43`); a
 bare `#43` is only a link and won't close anything. To point at a related
 issue that should stay open, drop the keyword and use `Refs #42`. Leave the