Filing Good Bugs

Writing good bugs is important when dealing with software development. I deal with several Bugzilla installations meaning I’ve got some experience with both good and bad bug reports. While the specifics may vary based on the product your submitting a bug report for these basics rules will make life easier for everyone. In many cases will even help things get resolved quicker.

Bugs that are easy to triage, sort and sift are easier to take care of than those that are cryptic and require more investigation. If you want your issue to be addressed promptly make sure you facilitate the process by writing a good bug report. It’s not difficult and doesn’t require much technical know how, it just requires being explicit yet concise. If more information is needed a developer can request it and explain how to capture it.

Summary

A good summary is explicit yet brief. Upon reading it the purpose is clear and little is left to question. Here are several poor summaries, and the ideal way to submit them:

Bad: “add me to planet”
Good: “add john doe to planet.mozilla.org”. There’s no ambiguity there. Just reading the subject I can distinguish it from others in the queue.

Bad: “site crashes browser”
Good: “visiting a video permalink page crashes IE6”. Less ambiguity just make sure to add the url to the bug.

Bad: “javascript error”
Good: “Contact form has a javascript error in Chrome”. Again less ambiguity is key.

Description

Descriptions should ideally be front loaded with the important information. If it’s a bug report and not a request it should be followed by steps to reproduce including what you see, and what you expect to see. Reference attachments as appropriate (screenshots can be helpful).

Bad: “Visiting a video permalink page crashes IE6.”
Good: “Upon visiting a video permalink page in IE6 the video automatically starts playing. About 10 seconds into the ad the browser crashes. I am able to reproduce this consistently at the following link: http://domain.tld/…”.

Bad: “Contact form shows a JS error, can’t submit.”
Good: “When attempting to submit the contact form [http:/doman.tld/…] in IE 7 I get a “object expected” error and it refuses to continue.”

Always include URL’s when applicable or examples on ways to reproduce the error when possible. It’s hard to act upon “several pages” when your site has over a half million pages.

Attachments

Screenshots, traces, debug logs, mockups are generally helpful. As a rule make try to use browser-readable formats when possible. JPEG, GIF, PNG for images, txt, or if you must PDF for documents. Having to open PowerPoint or Word to view your screenshot isn’t cool. It makes people avoid what would be helpful information. Explanations on what you’re seeing and expect to see are also helpful for when it’s not obvious to someone else.

Severity/Priority

Always try to use restraint when setting the severity or priority on a bug. Unless it’s truly a show stopper avoid using the most severe status. Generally speaking most “normal” or a P3 (on a P1 – P5 priority scale). Remember The Boy Who Cried Wolf.

Version

If you know the version, please specify it. It helps when several versions of a product are still floating around.

Product/Component

I put this toward the bottom for a reason. Making a best guess is the most you can generally do. Just be sure to read the entire list before deciding as the best option may be beyond the one you’ve already found.

Following these simple guidelines can go a long way to making sure bugs get resolved quicker.