Managing Bugs

How to do bug triage on the BugTracker.

1. Definitions

1.1. Status levels:

• UNCONFIRMED - no one's ever responded to this bug (bad)

• CONFIRMED - we're discussing a solution

• NEED_EXAMPLE - we need more information to progress

• IN_PROGRESS - a partial fix exists or fix exists but isn't yet integrated

• TESTING - a patch is merged, but poster has not confirmed it works, or it didn't reach the main repo yet

• RESOLVED - problem is fixed or was not a bug

1.2. Priorities

• critical - data loss or security issue

• urgent - bug that's blocking development or is a regression

• normal - bug that's not blocking development

• wish - would be nice

2. Regressions, and why they're a priority

We pay special attention to regressions, which are defined as "a bug that breaks something that worked in earlier releases". These issues should immediately be set to urgent. We should attempt to fix these bugs before the next release.

Because regressions may break workflows or tools that users have come to depend on, they are more important than other bugs that simply impede new ways of trying to use Mercurial. Large numbers of unaddressed regressions will also make upgrading risky and unattractive for users, which is unhealthy for a project.

Note that "performance regressions" generally do not meet the above definition, and thus should not necessarily be promoted to urgent.

Because regressions are higher priority than other bugs, bug fixes in one area that introduce a regression elsewhere are considered worse than no action. This will prevent certain classes of bugs from being fixed.

3. How to do triage

3.1. Handling individual bugs

• Get diagnostics first, give suggestions later (see Advice)

• Respond to new bugs as quickly as possible, especially where more info would be useful
• If it is a common issue, mark it as a duplicate
• Make sure its priority is set appropriately
• Make sure its title is useful (ie convert commands should mention the backend)
• Add appropriate developers to CC list
• Add appropriate topics
• Bugs that have long been fixed in main should be marked RESOLVED/FIXED
• Bugs that have been marked 'testing' can be marked RESOLVED/FIXED after two weeks if the user doesn't confirm earlier
• Bugs that have recently accepted patches should be marked TESTING
• Bugs with active work, including patches that aren't in main should be marked in IN_PROGRESS
• Bugs that require more info from the user should be marked NEED_EXAMPLE
• Bugs that remain in the NEED_EXAMPLE state for more than two weeks can be marked RESOLVED/INVALID
• Features and wishes that have been decided against should move to RESOLVED/WONTFIX

There is a hook installed on an hourly mirror of main that causes HgBot to update the BugTracker according to changelog commit messages. Summaries containing '(issueNNNN)' will automatically move issues to the testing state. References to issueNNNN in the body of the message will create references in that issue to the changeset. You can also explicitly write closes issueNNN or fixes issueNNN to move the bug into testing, or see issueNNN or addressesNNN to create a reference in the issue.

3.2. Dealing with third-party issues

If the third-party project is large enough to have its own BTS:

• assign to project maintainer or add URL for proper BTS

• mark the issue RESOLVED/INVALID

For smaller projects, we'll allow using our BTS to track issues if the maintainer is a known BTS user:

• assign to project maintainer
• reduce priority to bug or lower

• mark RESOLVED/INVALID if bug remains inactive

For any other projects:

• link to project homepage or extension page on wiki

• mark the issue RESOLVED/INVALID

3.3. Dealing with patches on the BTS

We don't accept patches on the BTS:

• they are hard to view
• they are hard to comment on
• they are hard to apply
• only people who are nosy on an issue see them
• there is no easy way to search the BTS for unapplied patches so if a patch isn't immediately applied, it is forgotten

So when someone adds a patch to the BTS (which already contains a link to ContributingChanges next to the attach button!), do the following immediately so the patch doesn't sit in limbo for years:

• immediately assign the bug to submitter
• mark the issue IN_PROGRESS

• add a comment that says "Read http://mercurial.selenic.com/wiki/ContributingChanges"

3.4. Marking Duplicates

• Choose whichever bug is resolved (or has a clear description) as the master
• Set superseder on the duplicate to point to the master, add a note, and set the bug as resolved
• If the master is not resolved, copy the nosy list from the duplicate and add a message pointing back to 'issueXXX'

3.5. Reducing Backlog

• Close out bugs that have been in UNCONFIRMED, TESTING, or NEED_EXAMPLE states too long

• Similarly, check if bugs marked IN_PROGRESS are really in progress

• Sort open issues by priority and activity - here is an old, invalid triage and an old, invalid unloved query

• Degrade long-standing bugs to features and features to wishes where appropriate

4. See also

• WritingTests

CategoryBugs CategoryDeveloper CategoryProcess