From f52bfaa55e6b815cbf5ad26a746c2c3868e2c5a9 Mon Sep 17 00:00:00 2001
From: Rootiest <chris@rootiest.com>
Date: Mon, 31 Aug 2026 22:27:26 -0400
Subject: [PATCH] docs(contributing): add PR description template and
 convention
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Codifies the PR body format the repo has converged on across its first
122 pull requests, which until now lived only as an implicit pattern
agents and contributors had to reverse-engineer from prior PRs.

- **`.github/PULL_REQUEST_TEMPLATE.md`** — `## Summary`, optional `##`
  sections, then `## Manual Verification` as a checkbox list. Gitea falls
  back to `.github/` when `.gitea/` is absent, and the GitHub mirror reads
  the same path, so one file covers both.
- **`CONTRIBUTING.md`** — new "Pull request descriptions" subsection under
  Branching & Pull Requests, documenting the same three-part structure.

Section names were chosen by frequency across all 122 PRs: `## Summary`
(86) and `## Manual Verification` (63) are the clear majority. The later
`## Manual Verification Checklist` (12, PRs 90-113), `## Test plan` (11)
and `## Verification` (3, PRs 121-122) variants are drift away from that
baseline, not a newer standard, so the template restores the dominant
form. Checkboxes ship unchecked but are meant to be checked before the
PR opens, matching the 585-to-12 ratio of `[x]` to `[ ]` in merged PRs.
---
 .github/PULL_REQUEST_TEMPLATE.md | 72 ++++++++++++++++++++++++++++++++
 CONTRIBUTING.md                  | 20 +++++++++
 2 files changed, 92 insertions(+)
 create mode 100644 .github/PULL_REQUEST_TEMPLATE.md

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..a89c456
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,72 @@
+<!--
+  PR title: Conventional Commits — type(scope): description
+    e.g. fix(mv): bring header and completions up to repo conventions
+    Lowercase after the colon, imperative mood, no trailing period.
+    Append `!` after the scope for a breaking change: feat(logging)!: ...
+    Types in use: feat, fix, docs, test, chore, perf, refactor, style.
+    See CONTRIBUTING.md § Commit Conventions.
+
+  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").
+-->
+
+## Summary
+
+<!--
+  What changed and why. A short prose paragraph, 2-5 bullets, or a
+  paragraph followed by bullets — whichever fits the change.
+
+  - Name concrete paths and identifiers in backticks (`functions/mv.fish`,
+    `$__fish_config_op_autoexec`), not vague descriptions.
+  - Lead a bullet with a **bold phrase** when it covers a distinct file or
+    behavior, so the list scans at a glance.
+  - Explain the reasoning, not just the diff — a reader should understand
+    why this approach over the obvious alternative.
+  - Say so explicitly when there is no behavioral change, when a file is
+    generated by the docs pipeline, or when the change is scoped to the
+    site build only.
+-->
+
+<!--
+  OPTIONAL SECTIONS — add any `##` heading here that the change actually
+  needs, and skip them entirely for a straightforward one. Used in this
+  repo, roughly in order of frequency:
+
+    ## Root cause          — for a bug fix, what was actually wrong
+    ## Why                 — motivation, when it isn't obvious
+    ## How it works        — mechanism, for a non-trivial new feature
+    ## Behavior            — user-visible behavior before/after
+    ## Changes             — a longer breakdown than Summary can carry
+    ## Docs                — documentation touched by this change
+    ## Notes               — caveats, follow-ups, deferred work
+    ## Scope note          — what this deliberately does NOT cover
+    ## Opinionated guard (C1-C6)
+                           — which tier gates this, and behavior when off
+    ## ⚠️ Breaking Change  — required whenever the title carries `!`;
+                             state the break and the migration path
+
+  A "Why not <alternative>?" heading is also common when a reviewer would
+  reasonably ask why the obvious approach was rejected.
+-->
+
+## Manual 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.
+
+  - One check per line, imperative, with the exact command in backticks
+    and the expected result stated.
+  - Cover the regression path, not just the happy path: the old behavior
+    still working, the opinionated toggle disabled, the error branch.
+  - Include the repo's standing gates when the change touches what they
+    guard: `fish -n <file>`, `fish_indent`, `python3 docs/verify-manual.py`,
+    `python3 docs/build-manual.py --site`, `fish tests/run-tests.fish`.
+  - Reset any universal variable you set during a check.
+-->
+
+- [ ] 
+- [ ] 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e61a79b..c2c76fc 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -64,6 +64,26 @@ assumes you *do* have push access (maintainers, regular contributors).
      approval before doing this** — there's no standing exception, no matter
      how trivial the change looks.
 
+### Pull request descriptions
+
+Fill in `.github/PULL_REQUEST_TEMPLATE.md` — Gitea and the GitHub mirror
+both pre-load it into the description box for you. Every PR carries, in
+this order:
+
+- **`## Summary`** — what changed and why, as a short paragraph, 2-5
+  bullets, or both. Name concrete paths and identifiers in backticks, and
+  explain the reasoning rather than restating the diff.
+- **Optional `##` sections** — add what the change actually needs
+  (`Root cause`, `Why`, `How it works`, `Behavior`, `Docs`, `Notes`,
+  `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.
+
 ## Commit Conventions
 
 Commit subjects follow [Conventional Commits](https://www.conventionalcommits.org/):