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 - 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 generated by the docs pipeline, or when the change is scoped to the
site build only. 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.
--> -->
<!-- <!--
+10 -3
View File
@@ -66,9 +66,8 @@ assumes you *do* have push access (maintainers, regular contributors).
### Pull request descriptions ### Pull request descriptions
Fill in `.github/PULL_REQUEST_TEMPLATE.md` — Gitea and the GitHub mirror Fill in `.github/PULL_REQUEST_TEMPLATE.md` — Gitea pre-loads it into the
both pre-load it into the description box for you. Every PR carries, in description box when you open a PR. Every PR carries, in this order:
this order:
- **`## Summary`** — what changed and why, as a short paragraph, 2-5 - **`## Summary`** — what changed and why, as a short paragraph, 2-5
bullets, or both. Name concrete paths and identifiers in backticks, and 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 means that step was *not* verified, so say so explicitly rather than
leaving it silently blank. 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 Conventions
Commit subjects follow [Conventional Commits](https://www.conventionalcommits.org/): Commit subjects follow [Conventional Commits](https://www.conventionalcommits.org/):