docs(agents): a merged PR closes its issue only via a closing keyword #47

Merged

pit merged 1 commit from docs/pr-closes-issue into main

2026-10-06 20:50:52 +00:00

pit commented

2026-10-06 20:49:42 +00:00

Owner

Summary

A merged pull request closes a referenced issue only when the reference carries a
closing keyword and lives where the action is read. The docs now say so, and bind
the /pr skill to it.

docs/agents/issue-tracker.md     # new section: "Pull requests close the issue they address"
AGENTS.md                        # new "### Pull requests" entry under Agent skills

The rule, in one place: put Closes #<index> in the pull request body. Fixes
and Resolves work too (the default keyword list). A bare #34 — in the title or
the body — is an ordinary cross-reference: it renders a link and adds a notice to
the issue, but carries no action, so the merge leaves the issue open. This is the
usual miss: the issue number in the PR title counts for nothing at merge time.

Body or commit message only. A keyword in a comment does nothing, and only
pull requests and commit messages can carry the action at all.
One keyword per issue. The keyword is read against the reference it precedes,
so Closes #34, closes #35, not one keyword over a list.
Related issues stay bare. A blocking or merely related #<index> is left
without a keyword, so a merge does not close unfinished work.

Evidence

The gap this documents, on the live instance (15.0.9+gitea-1.22.0): PR #44's
body carried no keyword — only a bare #34 in the title — so issue #34's timeline
shows a pull_ref notice and then a manual close event at 16:45:36Z, after the
merge. Issues #35 and #36 were likewise closed by hand. The docs state the fix.
Behaviour source: Forgejo 15.0 linked-references — the closing keywords
(close, closes, closed, fix, fixes, fixed, resolve, resolves,
resolved), the merge-time action, and the "PR description or commit message"
constraint.

Merge Danger

Door: two-way — docs only; git revert restores the prior text, and no
infrastructure, role or state is touched.

Blast Radius: low — two Markdown files; no code path changes.

## Summary A merged pull request closes a referenced issue only when the reference carries a closing keyword and lives where the action is read. The docs now say so, and bind the `/pr` skill to it. ```text docs/agents/issue-tracker.md # new section: "Pull requests close the issue they address" AGENTS.md # new "### Pull requests" entry under Agent skills ``` The rule, in one place: put `Closes #<index>` in the pull request **body**. `Fixes` and `Resolves` work too (the default keyword list). A bare `#34` — in the title or the body — is an ordinary cross-reference: it renders a link and adds a notice to the issue, but carries no action, so the merge leaves the issue open. This is the usual miss: the issue number in the PR **title** counts for nothing at merge time. - **Body or commit message only.** A keyword in a comment does nothing, and only pull requests and commit messages can carry the action at all. - **One keyword per issue.** The keyword is read against the reference it precedes, so `Closes #34, closes #35`, not one keyword over a list. - **Related issues stay bare.** A blocking or merely related `#<index>` is left without a keyword, so a merge does not close unfinished work. ## Evidence - **The gap this documents, on the live instance (15.0.9+gitea-1.22.0):** PR #44's body carried no keyword — only a bare `#34` in the title — so issue #34's timeline shows a `pull_ref` notice and then a manual `close` event at 16:45:36Z, after the merge. Issues #35 and #36 were likewise closed by hand. The docs state the fix. - **Behaviour source:** Forgejo 15.0 linked-references — the closing keywords (`close`, `closes`, `closed`, `fix`, `fixes`, `fixed`, `resolve`, `resolves`, `resolved`), the merge-time action, and the "PR description or commit message" constraint. ## Merge Danger **Door:** two-way — docs only; `git revert` restores the prior text, and no infrastructure, role or state is touched. **Blast Radius:** low — two Markdown files; no code path changes.

pit added 1 commit

2026-10-06 20:49:42 +00:00

docs(agents): a merged PR closes its issue only via a closing keyword ff00f9a518

Record that a pull request closes a referenced issue on merge only when the
reference carries a closing keyword (Closes #34, Fixes, Resolves) and lives in
the PR body or a commit message. A bare #34 — in the title or the body — is an
ordinary cross-reference: it links and notifies, and closes nothing, so the
issue is left to a manual close (what happened to #34, #35 and #36).

- AGENTS.md: a "Pull requests" entry under Agent skills, binding the /pr skill
  to write the keyword into the body.
- docs/agents/issue-tracker.md: the rules in full — body or commit message,
  the default keyword list, one keyword per issue, related issues left bare.

Grounded in Forgejo 15's linked-references behaviour and the live 15.0.9
instance, where the merged PR #44 carried only a bare #34 in the title and
issue #34 was closed by hand afterwards.