chore: strip issue-number refs from code comments; document the rule#144
Merged
Conversation
Remove `#NN` GitHub issue references from every Rust comment, doc-comment, and assert-message string across the workspace (27 files). Git already links code to its issue via commit/PR history, so an in-code `#NN` is redundant and rots when issues are renumbered or migrated. Prose was kept grammatical: trailing parentheticals dropped, leading label prefixes removed, and the handful of mid-sentence references rewritten. Only comments changed — no code, behaviour, or test logic. Requirement tags (FR5, G1) and feature slugs (F-capture) are preserved; they name stable design artifacts, not tickets. Codify the convention: - CONTRIBUTING.md — new file, full rationale (git-is-the-link, where issue numbers do/don't belong, boy-scout-not-crusade). - AGENTS.md — one-line entry in Conventions pointing to it.
- Acknowledge the one-time baseline sweep as the sanctioned exception to "no retroactive crusade" (the delivering PR would otherwise contradict it). - Drop "or closed" — a closed issue still resolves; only renumber/migrate break the link. - Reword the test-name example so the inline code span isn't line-final, bringing the line back under the 80-col convention.
This was referenced Jul 6, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Removes
#NNGitHub issue references from every Rust comment, doc-comment, andassert-message string across the workspace (27 files), and codifies the
convention that prompted the cleanup.
Why
Git already links code to its issue through commit/PR history
(
git blame → commit → PR → issue). An in-code#NNis redundant provenancethat rots silently when issues are renumbered, migrated, or closed — and a
reader can't act on it. Comments should say what/why at an altitude that
outlives any one ticket.
Scope & safety
near-perfect 1:1 line swap (420/420 on the code files).
#NN:label prefixes removed, andthe handful of mid-sentence references rewritten to stay grammatical.
FR5,G1) and feature slugs(
F-capture) — they name stable design artifacts, not tickets — and all#[...]Rust attributes.ROADMAP.md/PRD prose;those are untouched.
The rule, written down
CONTRIBUTING.md(new) — full rationale: git-is-the-link, where issuenumbers do/don't belong, and boy-scout-not-crusade for future edits.
AGENTS.md— one-line entry in Conventions pointing to it.Verification
cargo fmt --check,cargo clippy --workspace --all-targets -D warnings, andcargo test --workspaceall pass (the lone failure is the pre-existingsandbox-only
ptyopenpty test, unrelated).markdownlint-cli2clean on thenew/edited docs.