Writing an Effective Bug Report

This is a short excerpt from Practical Development Environments and contains a number of useful links to other guidelines.

~Matt

The three key points to bear in mind when creating a bug report should be:

• How to reproduce the bug, as precisely as possible, and how often this will make the bug appear
• What should have happened, at least in your opinion
• What actually happened, or at least as much information as you have recorded

Many applications can generate a textual description of how they have been installed and configured. If such a description is available, you should always add it to the bug. The application may also contain some tests to check that it is still configured correctly. If so, you should run the tests and attach their results too.

As well as providing correct and useful information in the bug, it's important to check that you behave as expected for the project. This is especially true for open source projects. Maybe you should ask questions first on a users' mailing list before escalating the issue to a developers' mailing list? Or you may mark a bug as maximum priority, because it's stopping your work, only to see it downgraded because no one else is blocked by that bug. Etiquette is important, and imperious commands to "fix this bug immediately" rarely help anything.

One common cause of frustration with bug tracking systems is related to how their information is added. Bugs are too often added with vague descriptions, missing information, premature conclusions, or a best guess at the real build label. A classic situation is when a complex program has a bug deep inside it, but the only error message that is visible is one from some unrelated area. That area often gets bugs from the deeper level assigned to it, much to the frustration of the developer responsible for it. Adding some good local documentation to wherever people add new bugs can go a long way to improving the quality of all the bugs.

Some useful documents with general advice about creating bugs include the Mozilla Project's Bug Writing Guidelines and Simon Tatham's How to Report Bugs Effectively. There are also many examples of more site-specific documents about writing bug reports; these contain product specific information such as descriptions of what each part of the product does. Two of these are Opera's Guidelines for Filing Good Bug Reports and FreeBSD's Writing FreeBSD Problem Reports.

Slightly off-topic, but also useful, is Eric S. Raymond and Rick Moen's classic article How to
Ask Questions the Smart Way. This document has some excellent reminders and strong opinions about how to interact well with groups of technical volunteers.