TimZander / TimZander/claude

standards: never put a closing keyword next to an issue number, even to negate it

Open Beginner friendly
#190 0 comments 0 reactions 0 assignees View on GitHub

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 closingIssuesReferencesWILL 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 #N with 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 closingIssuesReferences is 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_message default:

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 closingIssuesReferences covers only the description
  • The gh pr merge --squash --body remedy 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.