This page is primarily intended for developers of Mercurial.

Managing Bugs

How to do bug triage on the BugTracker.

1. How to do triage

It's important to approach bug reports as a triage problem. Some reports are five-alarm fires, some are papercuts. We need to make sure that we don't miss the former while we're addressing the latter. And we need to be honest that we're probably not going to have time to address the latter.

The most crucial step in this process is 'intake': dealing with newly-reported issues. We need to quickly and aggressively categorize these and then move them out of the intake stage. Bug reporters are likely to vanish within a couple days so we have only a narrow window to get any information we need from them. Every new bug you look at should be moved to one of these states:

First responders should:

First responders should not:

2. Definitions

2.1. Status levels:

2.2. Priorities

2.3. 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 unless they're intolerably large, 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. HG Bot and the BTS Reaper

There is a hook called HgBot to update the BTS 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.

There is also a nightly process called the BTS Reaper that automates some bug gardening:

4. Manual bug gardening hints

In addition to the above, we should try to keep the BTS data high-quality:

4.1. Marking Duplicates

4.2. Dealing with third-party issues

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

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

For any other projects:

4.3. Dealing with patches on the BTS

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:

5. Attacking the backlog

We will likely always have a backlog of issues that exceeds our development capacity, so it's tempting for developers to ignore the BTS and just work on features.

6. See also

CategoryBugs CategoryDeveloper CategoryProcess

ManagingBugs (last edited 2015-03-11 18:18:47 by mpm)