Simply put, the more effectively you report a bug, the more likely an engineer will actually fix it.

These guidelines are a general tutorial to teach how to compose effectivebug reports in maemo.org Bugzilla.

How to Write a Useful Bug Report

A useful bug report normally has two qualities:

  1. Reproducible. If engineers can't see the bug themselves to prove that it exists, they will probably stamp yourbug report "WORKSFORME" and move on to the nextbug. Every detail you can provide helps.

  2. Specific. The quicker the engineers can isolate thebug to a specific area, the more likely they'll fix it. (If a programmer or tester has to decipher a bug, they may spend more time cursing the submitter than solving the problem.)

    [ Tell Me More ]

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:

BAD: "My browser crashed. I think I was on www.foo.com. By the way, your Back icon looks like a squashed rodent. And my grandmother's home page is all messed up in your browser. Thx 4 UR help."

GOOD: "The browser crashed each time I went to www.foo.com, using the browser on version 4.2008.23-14 (Diablo)."

It again crashed each time upon 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://www.foo.com/images/topics/topicfoos.gif" width="34" height="44" border="0" alt="News">

How to Enter your Useful Bug Report into maemo.org Bugzilla:

Before you enter your bug, use Bugzilla's search page to determine whether the defect you've discovered is a known, already-reported bug. Please avoid filing duplicates.

Next, be sure to reproduce your bug using the latest available version. Engineers tend to be most interested in problems affecting the code base that they're actively working on. After all, the bug you're reporting may already be fixed.

If you've discovered a new bug using a current version, report it in maemo.org Bugzilla by filling out the Enter a new bug form:

Where did you find the bug?

Product: In which product did you find the bug?

Version: In which product version did you find the bug?
Note that Diablo (4.2008.23-14) corresponds to version 4.1.

Platform: On which hardware did you find the bug?

Component: In which component does the bug exist?
Bugzilla requires that you select a component to enter a bug. (Not sure which to choose? Click on the Component link. You'll see a description of each component, to help you make the best choice.)

OS: On which Operating System (OS) did you find this bug? (e.g. Maemo, Linux, Windows, Mac OS X)
In most cases you want to set "Maemo" here (Maemo is the operating system running on Nokia Internet Tablet devices). Otherwise, select the OS that you found the bug on, or "other" if your OS isn't listed.

How important is the bug?

Severity: How damaging is the bug?
This item defaults to 'normal'. Please do not set bugs to Blocker or Critical just because you think that your issue deserves highest importance. If you're not sure what severity your bug deserves, click on the Severity link. You'll see a description of each severity rating.

Priority and Target Milestone
Please keep the priority set to Low and the Target Milestone unset. Bugs will not be fixed faster just because the reporter sets a Target Milestone value that will be unset again by the developers. Providing a useful report or even a patch is much more successful.

What else can you tell the engineer about the bug?

Summary:
A good summary should quickly and uniquely identify a bug report.
A useful summary might be "Modest crashes when fetching from Gmail over IMAP" or "Center dpad press is treated as Enter key, triggering form submit instead of activating finger keyboard". A bad summary would be "Software fails" or "Cannot send mail".

[ Tell Me More ]

Description:
Please provide a detailed problem report in this field. Your bug's recipients will most likely expect the following information:

SOFTWARE VERSION: You can find this at Control Panel > General > About product.

STEPS TO REPRODUCE THE PROBLEM: A minimized, easy-to-follow step-by-step description that will trigger the bug. Include any special setup steps.

EXPECTED OUTCOME: What the application should have done, were the bug not present.

ACTUAL OUTCOME: What the application did after performing the above steps.

REPRODUCIBILITY: Is this bug always reproducible (this means that you have tried several times and not just once), or only sometimes?

EXTRA SOFTWARE INSTALLED: Is any special software installed that might be related to the problem?

OTHER COMMENTS: Any other information that might be useful.

You're done!

After double-checking your entries for any possible errors, press the "Commit" button, and your bug report will now be in the maemo.org Bugzilla database.

More Information on Writing Good Bugs

1. General Tips for a Useful Bug Report

Use the explicit structure proposed by the template, so yourbug reports are easy to skim.

Avoid cuteness if it costs clarity. Nobody will be laughing at your funny bug title at 3:00 AM when they can't remember how to find your bug.

One bug per report. Completely different people typically fix, verify, and prioritize different bugs. If you mix a handful of bugs into a single report, the right people probably won't discover your bugs in a timely fashion, or at all. Certain bugs are also more important than others. It's impossible to prioritize a bug report when it contains four different issues, all of differing importance.

No bug is too trivial to report. Unless you're reading the source code, you can't see actual software bugs, like a dangling pointer -- you'll see their visible manifestations, such as the segfault when the application finally crashes. Severe software problems can manifest themselves in superficially trivial ways. File them anyway.

2. How and Why to Write Good Bug Summaries

You want to make a good first impression on the bug recipient. Just like a New York Times headline guides readers towards a relevant article from dozens of choices, will your bug summary suggest that your bug report is worth reading from dozens or hundreds of choices?

Conversely, a vague bug summary like install problem forces anyone reviewing installation bugs to waste time opening up your bug to determine whether it matters.

Your bug will often be searched by its summary. Just as you'd find web pages with Google by searching by keywords through intuition, so will other people locate your bugs. Descriptive bug summaries are naturally keyword-rich, and easier to find.

For example, you'll find a bug titled "Dragging icons from List View to terminal application doesn't paste path" if you search on "List", "terminal", or "path". Those search keywords wouldn't have found a bug titled "Dragging icons doesn't paste".

Ask yourself, "Would someone understand my bug from just this summary?" If so, you've written a fine summary.

Don't write titles like these:

  1. "Can't install" - Why can't you install? What happens when you try to install?
  2. "Severe Performance Problems" - ...and they occur when you do what?
  3. "back button does not work" - Ever? At all?

Good bug titles:

  1. "Modest crashes when fetching from Gmail over IMAP" - Explains problem and the context.
  2. "Center dpad press is treated as Enter key, triggering form submit instead of activating finger keyboard" - Explains what happens, and the context.