From f52bfaa55e6b815cbf5ad26a746c2c3868e2c5a9 Mon Sep 17 00:00:00 2001 From: Rootiest Date: Mon, 31 Aug 2026 22:27:26 -0400 Subject: [PATCH 1/4] 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 @@ + + +## Summary + + + + + +## Manual Verification + + + +- [ ] +- [ ] 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/): -- 2.54.0 From 2f49960149126d64a01f6154e01e7366c3bebb4e Mon Sep 17 00:00:00 2001 From: Rootiest Date: Mon, 31 Aug 2026 22:32:52 -0400 Subject: [PATCH 2/4] docs(contributing): establish Closes #N issue-linking convention MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The repo has no issue-tracking history yet — a grep across all 122 prior PRs found zero `Closes #N` references — so this is forward-looking rather than derived from precedent. Establishing it now means the first PR that does close an issue has a rule to follow instead of inventing one. - Placement is a trailing line at the end of `## Summary`, not the bottom of the body, because `## Manual Verification` is always last. - `Fixes`/`Resolves` noted as equivalent; `Refs #N` for a related issue that should stay open. - Guidance calls out that the keyword must be repeated per issue, since a bare `#43` after a comma links without closing. - Lives in the template's HTML comments, so a PR with no associated issue leaves no stray `Closes #` behind. Also drops an unverified claim that the GitHub mirror pre-loads the template; PRs are opened on Gitea, and the mirror is push-only. --- .github/PULL_REQUEST_TEMPLATE.md | 14 ++++++++++++++ CONTRIBUTING.md | 13 ++++++++++--- 2 files changed, 24 insertions(+), 3 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index a89c456..8c7f886 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -26,6 +26,20 @@ - 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. + + 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: + + Closes #42 + + Gitea and GitHub both auto-close the issue on merge. `Fixes #N` and + `Resolves #N` work identically; pick whichever reads correctly. Use one + line per issue (`Closes #42, closes #43` — the keyword must be repeated, + a bare `#43` after a comma is only a link and will NOT close). For an + issue that is related but should stay open, reference it without a + keyword: `Refs #42`. Omit all of this entirely when no issue is involved + — do not leave an empty `Closes #` behind. --> ## 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