standards: never put a closing keyword next to an issue number, even to negate it
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 0
- Forks
- 1
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 7
Description
Problem
GitHub's issue-closing parser matches (close|closes|closed|fix|fixes|fixed|resolve|resolves|resolved) followed by #N, and has no concept of negation. A phrase that explicitly says a PR does not resolve an issue still links and closes it.
Hit three times in a single session on TimZander/AudioClassifier #195:
| Where | Text | Effect |
|---|---|---|
| PR body | ## Scope — this does not close #190 |
gh pr view 195 --json closingIssuesReferences → WILL CLOSE: #190 |
commit db40bfa |
Records but does not fix #196 |
would have closed an issue filed an hour earlier, for a live bug |
commit 6e9582d |
Deferred, not fixed: #203 |
same trap, in the very commit documenting the lesson |
All three issues described open, unfixed bugs. Merging would have marked three live defects as resolved.
Why it bites twice
The PR description is trivial to fix and GitHub re-parses on edit. Commit messages are not. They close issues independently when they land on the default branch, and rewording a pushed commit needs a force push — which standards/CLAUDE.md prohibits. Worse, AudioClassifier has squash_merge_commit_message: COMMIT_MESSAGES, so commit bodies are concatenated into the squash commit and the keywords land even when the PR body is clean.
The escape hatch is not obvious: the merger can set the squash message explicitly, which overrides the repo default. No force push required — but only if it is done in the merge command itself.
Proposed rule for standards/CLAUDE.md
Under Branch Naming and PR Linking:
Never write a closing keyword adjacent to an issue number, even to negate it. GitHub matches
closes/fixes/resolves(and conjugations) followed by#Nwith no understanding of negation — "does not close #190" closes #190. Write "#190 stays open" or "leaves #190 open" instead. This applies to commit messages as much as PR descriptions: keywords in commits close issues when they land on the default branch, and rewording a pushed commit requires a force push.Verify before merging.
gh pr view <N> --json closingIssuesReferencesis GitHub's own parse and is authoritative for the description:gh pr view <N> --json closingIssuesReferences --jq '.closingIssuesReferences[] | "WILL CLOSE: #\(.number)"'Empty output means the description closes nothing. It does not cover commit messages — check those separately:
git log origin/main..HEAD --format='%B' \ | grep -inE '(close|closes|closed|fix|fixes|fixed|resolve|resolves|resolved)[ :]+#[0-9]+'If a commit message already contains one, you do not need a force push. Set the squash commit message explicitly at merge time — it overrides the repo's
squash_merge_commit_messagedefault:gh pr merge <N> --squash --subject "..." --body "$(cat <<'ENDOFBODY' ...clean body, no closing keywords next to issue refs... ENDOFBODY )"This only works if done in the merge command itself; relying on someone to hand-edit the box in the web UI is not a control.
Acceptance criteria
- Branch Naming and PR Linking carries the negation warning with the "#N stays open" alternative
- Both verification commands included, with the note that
closingIssuesReferencescovers only the description - The
gh pr merge --squash --bodyremedy documented as the no-force-push fix - Notes the remedy must happen in the merge command, not the web UI
Notes
The existing standard already tells developers to write Closes #N to link issues. This is the missing other half: the same words fire when you mean the opposite.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Read the Branch Naming and PR Linking section of standards/CLAUDE.md and compare it with the stated acceptance criteria. Document the negation warning, both verification commands, and the explicit gh pr merge --squash remedy, including that it must be applied in the merge command rather than the web UI.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- git, github, shell
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 88/100