effective work with a bug reporting system

Again and again I stumble over people who seemingly don't understand how a bug reporting system is supposed to be used - usually that's Mozilla's Bugzilla in my case.

Those systems can work very well for reporting and working on bugs, and even though it could be improved (yes, all improvements I'd like are filed as bugs themselves), Bugzilla has grown into a really good such system over the years. To be honest, I've never professionally studied such technologies, and Bugzilla is the only one I know really well, but when you're working with it long enough and think about it, you begin to understand what this is all about.

One common mistake people are making is to go into a bug report that already has 50 or more comments and is pretty lengthy, and then they request some detail change in some part of the work that has already been done, reviewed and landed there. A recent comment in the "new SeaMonkey theme" bug doing exactly that is what leads me to write this blog entry. The correct solution to deal with such issues caused by a different bug (esp. if that one is a lengthy report already) is to file a new "followup" bug that covers exactly that one detailed issue you're seeing and mark this new bug dependent on the original one. Leaving a comment in the original bug can also help to get attention to the new issue, but that comment shouldn't be more than "I found a problem with X caused by this checkin, see bug XXXXXX" (Bugzilla is intelligent enough to link your mentioning of "bug XXXXXX" to the actual bug report).

Another common mistake is to add comments to the bug that don't add anything that wasn't already said there, esp. comments that just tell "I'm seeing this too" or "I want this fixed as well" or even "Adding myself to the CC list". "Me too" is only useful if you tell that you're seeing this on a configuration where it wasn't clear before that it is affected by the bug. If developers already know the cause for the problem or are convinced that this should be fixed, a "me too" comment just wastes their time - they need to read it and get no new information from that read, while they could use the same time to already actually work on a fix. You're probably distracting other people from work with such comments, keep that in mind.

I even believe that discussion of how some implementation should work in concept is usually wrong for a bug report. Bug reports should focus on explaining what exactly is the issue, finding out its root cause, and the actual fix (along with reviews of that fix). That's even true for feature requests. If the design of such a feature is unclear, this should be discussed in some place that allows to do this more in a real discussion style, allows easy editing of drafts, etc. Use a newsgroup, a wiki page, or both, or whatever fits this issue, link that from the bug, and come back to the bug when the discussion has settled on a specific approach.

So, actually, effective use of such a system comes down to:

• Care that there's one bug report per specific issue, avoid the need for multiple patches/fixes in a single bug report.
• If you want to track multiple or general issues, use a tracking bug for that (such a bug has multiple specific reports marked as dependencies and no specific work/fix/patch by itself)
• Only add comments that add further information that helps to resolve the bug
• Care that new people who look at the bug report can easily get informed of what the specific issue is and how far a fix has been progressed
• File followup bugs for any derived specific issues, such as regressions, improvements to already passed (reviewed/checked in) fixes (unless you're very sure of a logical one-line-fix or that a backout is the only chance to fix the derived issue)
• When filing new bugs, make sure that all information someone else (a developer) needs to fix this bug is there. If you're not sure what such a developer needs, describe the details of the problem you found (when/where/how it happened to you, what version of what software you were using for that, what you were doing in detail)
• If a developer tells you to file a followup or take the discussion somewhere else, just do it - even if you don't understand why this may be a good idea. If you request a fix done by someone else, it's usually a good idea to also follow his requests that ease him working/helping on a fix. It's usually a good idea to add a comment on the bug that says "requested followup is bug XXXX" or "I opened a thread for this discussion at http://foo/bar" or "The requested draft is on the wiki at http://foo/wiki/bar". Helping developers by following their requests can magically speed up fixing

I'm sure this set of common mistakes and guidelines is incomplete, but I think if you follow this advice, working with Bugzilla and other bug reporting systems will not only be more fun for everyone, but also will make fixes appear faster as developers can be more foused to specific working tasks.