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:
@@ -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
@@ -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/):
|
||||||
|
|||||||
Reference in New Issue
Block a user