docs(contributing): establish Closes #N issue-linking convention

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.
This commit is contained in:
2026-08-31 22:32:52 -04:00
parent f52bfaa55e
commit 2f49960149
2 changed files with 24 additions and 3 deletions
+14
View File
@@ -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.
-->
<!--