Writing a good bug report

• Bug reporting
• Bug-tracking systems
• Is this a new bug?
• A useful bug report
• If your report or comment gets blocked
• Following up

Bug reporting¶

When you run into an issue with ASF instrastructure, with the software one of the ASF projects produces, or with an ASF-related website, you may be the first person to have noticed the issue. If so, you should report it. The people responsible for the thing that has a bug or other issue will be happy to know about the problem so they can fix it before more people run into it.

For the purposes of this discussion, we'll call any issue, from a calculation error in a function to a punctuation error on a web page, a "bug". Something that you would like to see added to an application or a website to make it better would be an "enhancement request". Both are useful; we are looking at bugs here.

Bug-tracking systems¶

ASF has two bug-tracking systems:

• Jira
• Bugzilla

Infra itself uses Jira. To submit a ticket for Infra, search for the INFRA project.

Projects can use either system, or some other method of tracking bugs. If the bug you found is in a project's application or website, you need to find out where that project wants to hear about it. If you cannot find the project in either Jira or Bugzilla, ask for advice on the project's dev@ or users@ mailing list.

Is this a new bug?¶

Before spending the time filing a bug report, it's useful to check whether a report about the bug you found already exists. If so, you can add comments or additional information to the existing report.

Infra maintains several real-time status pages. If the infrastructure issue you ran into is reported on one of these pages, Infra already knows about it.

If what you found seems to be a new bug, you get to report it!

A useful bug report¶

Useful bug reports get bugs fixed. A useful bug report is usually:

• Reproducible. If a developer or sysadmin can't see it or conclusively prove that it exists, they may stamp it "WORKSFORME" or "INVALID", and move on to the next bug. Every detail you can provide helps.
• Specific. The quicker the person looking at your report can connect your issue to a specific problem, the quicker they can fix it.

Let's say the application you're testing is a web browser. You crash at foo.com, and want to write up a bug report:

A bad report: "My browser crashed. I think I was on foo.com. My computer uses Windows. I think that this is a really bad problem and you should fix it now. By the way, your icons really suck. Nobody will use your software if you keep those ugly icons. Oh, and my grandmother's home page doesn't look right, either, it's all messed up. Good luck.

A good report: "I crashed each time when I went to foo.com, using the 10.28.99 build on a Win NT 4.0 (Service Pack 5) system. I also rebooted into Linux, and reproduced this problem using the 10.28.99 Linux build. The browser crashed each time while drawing the Foo banner at the top of the page. I broke apart the page, and discovered that the following image link will crash the application reproducibly, unless you remove the "border=0" attribute: <IMG SRC="http://foo.com/images/topics/topicfoos.gif" width=34 height=44 border=0 alt="News">"

When you enter a bug report, both Bugzilla and Jira provide some helpful fields where you can select things like your operating system. If you are reporting a bug via email to a project, you need to remember to provide all the relevant information that could help identify the source of the problem.

Once you have established the conditions (operating system, web browser, and so on), include the steps to reproduce the problem:

1. What you wanted to do.
2. The steps you took to do it.
3. What you expected to happen.
4. What actually happened.

If you can capture onscreen error messages, extracts from logs, or relevant screen shots, include them in the report.

The bug-tracking systems allow you to suggest a severity for the bug. If you are reporting by email, explain the urgency of getting the bug fixed.

Make sure you provide a useful title for the report:

• Useful: "PCMCIA install fails on Tosh Tecra 780DVD w/ 3c589"
• Not useful: "Browser crashes" or "Install problem"

Review Creating a Jira ticket for specifics about Jira bug reports.

What not to include

Adding editorial comments ("what sort of idiot would release a product with such a bug?") is worse than useless. It sets you up as a critic rather than a partner to the people whose help you need.

If your report or comment gets blocked¶

Infra uses various tools and techniques to prevent spammers from posting material on Jira. If your new bug report, or comment on an existing report, gets blocked, contact Infra so we can resolve the issue and fine-tune our spam filters.

Following up¶

In either bug tracking system you can arrange to get updates whenever the status of the bug report changes. If you are reporting by email and want to get updates sent to one or more email addresses, specify them.

Based on contributions from Eli Goldberg, Claudius Gayle, Peter Mock, Chris Pratt, Tom Schutter, and Chris Yeh.