Skip to content

[3.0] Say that an issue report covers one bug - #9523

Merged
Sesquipedalian merged 1 commit into
SimpleMachines:release-3.0from
albertlast:docs/one-bug-per-issue
Aug 15, 2026
Merged

[3.0] Say that an issue report covers one bug#9523
Sesquipedalian merged 1 commit into
SimpleMachines:release-3.0from
albertlast:docs/one-bug-per-issue

Conversation

@albertlast

Copy link
Copy Markdown
Collaborator

Note

This change was produced by an LLM. The wording and the commit message were
written by Claude (Anthropic), driven by @albertlast. It has not yet had human
code review.

Description

@Sesquipedalian asked for this on #9520:

For future reference for AI agents: don't report two or more unrelated bugs in a
single issue report.

AGENTS.md is the file the agents working on this repository read — GitHub Copilot,
Codex, Cursor and Gemini CLI read it directly, and Claude Code reads it through
CLAUDE.md — so that request belongs in it, or the next agent will make the same
mistake. Nothing outside that file changes.

The new ## Reporting bugs section records two things:

  • One bug per report, with the reason rather than just the rule: an issue is closed
    by the pull request that fixes it, so a report carrying several unrelated bugs cannot
    close honestly. Either it shuts while part of what it describes is still broken, or it
    stays open long after the part somebody cared about is done. Related findings get filed
    separately and linked instead.
  • Check whether a fix is already open before filing, and search by file rather than
    by title. Half of [3.0]: Two fatals: the board index with unapproved posts, and the CLI installer #9520 turned out to be fixed already by [3.0][Testing] Install the forum from the command line #9344, which is titled as a
    testing change and gives no hint from its title that it touches the installer bug in
    question — the sort of miss that reads as carelessness from the outside.

Why this failure mode is worth documenting: it comes from the way agents find these bugs.
Sweeping an area turns up several defects at once, and writing them up together feels
tidier than opening five reports. It is not, for whoever has to close them.

Issues References (Fixes|Related|Closes)

  1. Related: [3.0]: Two fatals: the board index with unapproved posts, and the CLI installer #9520 (where the request was made)

Asked for on SimpleMachines#9520: "don't report two or more unrelated bugs in a single
issue report". The reason is what happens afterwards -- an issue is closed
by the pull request that fixes it, so a report carrying several unrelated
bugs cannot close honestly.

Also records that a fix may already be open in a pull request whose title
says nothing about it, and how to find that by file rather than by title.

Signed-off-by: albertlast <mathiaspapealbert@hotmail.com>
@Sesquipedalian
Sesquipedalian merged commit 4d4c1a5 into SimpleMachines:release-3.0 Aug 15, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants