From 2f49960149126d64a01f6154e01e7366c3bebb4e Mon Sep 17 00:00:00 2001
From: Rootiest <chris@rootiest.com>
Date: Mon, 31 Aug 2026 22:32:52 -0400
Subject: [PATCH] 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.
 -->
 
 <!--
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c2c76fc..0e3a3dd 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -66,9 +66,8 @@ assumes you *do* have push access (maintainers, regular contributors).
 
 ### 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:
+Fill in `.github/PULL_REQUEST_TEMPLATE.md` — Gitea pre-loads it into the
+description box when you open a PR. 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
@@ -84,6 +83,14 @@ this order:
   means that step was *not* verified, so say so explicitly rather than
   leaving it silently blank.
 
+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
+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
+line out entirely when no issue is involved.
+
 ## Commit Conventions
 
 Commit subjects follow [Conventional Commits](https://www.conventionalcommits.org/):