Bug writing guidelines

  • Revision slug: Bug_writing_guidelines
  • Revision title: Bug writing guidelines
  • Revision id: 12868
  • Created:
  • Creator: Chrisblore
  • Is current revision? No
  • Comment initial stab at sorting some of the formatting

Revision Content

Why You Should Read This

The Mozilla bug tracking system ([http://bugzilla.mozilla.org Bugzilla) allows any interested individuals on the Internet to directly report and track bugs in mozilla.org open-source projects like the Mozilla Application Suite or Mozilla Firefox. Like you, Mozilla QA (Quality Assurance) wants your bug reports to result in bug fixes; the more effectively a bug is reported, the more likely that an engineer will actually fix it. By following these guidelines, you can help ensure that your bugs stay at the top of the Mozilla engineers' heap, and get fixed. Bugzilla is the preferred method of submitting a bug - the linked entry form incorporates parts of these guidelines.

How to Write a Useful Bug Report

Useful bug reports are ones that get bugs fixed. A useful bug report normally has two qualities:

  1. Reproducible. If an engineer can't see it or conclusively prove that it exists, the engineer will probably stamp it WORKSFORME or INVALID, and move on to the next bug. Every relevant detail you can provide helps.
  2. Specific. The quicker the engineer can isolate the issue to a specific problem, the more likely it'll be expediently fixed. If you're crashing on a site, please take the time to isolate what on the page is triggering the crash, and include it as an HTML snippet in the bug report if possible. (Specific bugs have the added bonus of remaining relevant when an engineer actually gets to them; in a rapidly changing web, a bug report of "foo.com crashes my browser" becomes meaningless after the site experiences a half-dozen redesigns and hundreds of content changes.)

Let's say you crash at foo.com, and want to write up a bug report:

BAD: "My browser crashed. I think I was on foo.com. I think that this is a really bad problem and you should fix it or else nobody will use your browser. By the way, my sister thinks your icons really suck. Oh, and my mom's home page doesn't look right, either, it's all messed up. Thx 4 fixing theze bugz." GOOD: "I crashed each time when I went to foo.com, using Mozilla on a Win NT 4.0 (Service Pack 5) system. The build ID is 20030609. I also rebooted into Linux, and reproduced this problem using the 20030608 Linux build. Mozilla 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 Mozilla 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">

If your problem is Mozilla crashing, Talkback data is very helpful to engineers trying to diagnose the problem. If you can consistently reproduce the crash, please download a build with Talkback and install it. Then, do what is necessary to reproduce the crash, and follow the instructions for sending crash data to the server. Lastly, run the program components/talkback.exe (Win32) or components/talkback/talkback (Unix) and find your "Incident ID". Include this with the bug report. Please don't paste the raw Talkback data into your bug. We'd also recommend reviewing a few of the better bug reports, such as 2683, 3092 or 4044. Bug submissions that do not meet these "Useful Bug Report" criteria tend to be investigated on a time-available basis, if investigated at all.

How to Enter your Useful Bug Report into Bugzilla

Before you enter your bug, you need to make sure it has not been previously reported. There is a tutorial on the best ways of doing this. Next, be sure that you've reproduced your bug using a build released within the past three days. Our development process moves at lightning speed, and the bug you've found may already have been fixed. (Nightly builds can be downloaded from the mozilla.org binaries page.) If you've discovered a new bug using a current build, report it in the guided Bugzilla entry form.

1. Are you sure you don't want to use the guided form? :-) You won't have to read the rest of this page if you do... 2. OK, then. From the Bugzilla main page (http://bugzilla.mozilla.org), choose "Enter a new bug". 3. Select the product that you've found a bug in. 4. If you haven't logged into Bugzilla already, you'll need to enter your email address, password, and press the "Login" button. (If you don't yet have a password, enter your email address below and press the "Submit Request" button instead. You'll receive an email message with your password shortly.)

Now, fill out the form. Here's what it all means:

Where did you find the bug?

Product: In which product did you find the bug? You just filled this out on the last page. Version: In which product version did you find the bug? We're not yet using this field. Just leave the default value as you found it. ;) Component: In which component does the bug exist? Bugzilla requires that you select a component to enter a bug. (If they all look meaningless, click on the Component link, which links to descriptions of each component, to help you make the best choice.) Platform: On which hardware platform did you find this bug? (e.g. Macintosh, SGI, Sun, PC.) If you know the bug happens on all hardware platforms, choose 'All'. Otherwise, select the platform that you found the bug on, or "Other" if your platform isn't listed. OS: On which Operating System (OS) did you find this bug? (e.g. Linux, Windows NT, Mac OS X) If you know the bug happens on all OSs, choose 'All'. 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'. (To determine the most appropriate severity for a particular bug, click on the Severity link for a full explanation of each choice, from Critical to Enhancement.)

Who will be following up on the bug?

Assigned To: Which engineer should be responsible for fixing this bug? Bugzilla will automatically assign the bug to a default engineer upon submitting a bug report; the text box exists to allow you to manually assign it to a different engineer. (To see the list of default engineers for each component, click on the Component link.) Cc: Who else should receive e-mail updates on changes to this bug? List the full e-mail addresses of other individuals who should receive an e-mail update upon every change to the bug report. You can enter as many e-mail addresses as you'd like; e-mail addresses must be separated by commas, with no spaces between the addresses.

You would not normally change either of these fields from their default values.

What else can you tell the engineer about the bug?

URL: On what URL did you discover this bug? If you encountered the bug on a particular URL, please provide it (or, them) here. If you've isolated the bug to a specific HTML snippet, please also provide a URL for that, too or, preferably, return to the bug after you've submitted it and add the HTML snippet as an attachment.

Summary: How would you describe the bug, in approximately 60 or fewer characters? A good summary should quickly and uniquely identify a bug report. Otherwise, developers cannot meaningfully query by bug summary, and will often fail to pay attention to your bug report when reviewing a 10 page bug list. Think of it as a "title". A summary of "Drag-scrolling any web page crashes Mac OS X builds" is a useful title. "Crash" or "Drag Crash" would be examples of a bad title.

Description: What else can you tell the engineer about this bug? Please provide as detailed of a problem diagnosis in this field as possible, including as much as possible of the following information:

Overview Description: More detailed expansion of summary. Drag-selecting any page crashes Mac OS X builds in NSGetFactory Steps to Reproduce: The minimal set of steps necessary to trigger the bug. Include any special setup steps. 1) View any web page. (I used the default sample page, resource:/res/samples/test0.html) 2) Drag-select the page. (Specifically, while holding down the mouse button, drag the mouse pointer downwards from any point in the browser's content region to the bottom of the browser's content region.)

Actual Results: What the application did after performing the above steps.

The application crashed. Stacktrace appended below from gdb.

Expected Results: What the application should have done, were the bug not present. The window should scroll downwards. Scrolled content should be selected. (Or, at least, the application should not crash.)

Build Date & Platform: Date and platform of the build that you first encountered the bug in. (The build date can be found as part of the window title, in YYYYMMddHH format.) 2003060709 installer build on Mac OS X

Additional Builds and Platforms: Whether or not the bug takes place on other platforms or browsers.

- Occurs On Seamonkey (20030605 build on Windows 2000) - Doesn't Occur On Seamonkey (20030602 build on Suse Linux), IE 6 (Windows XP), Netscape Navigator 4.5 (Mac OS) Additional Information: Minimized HTML snippets, Talkback crash IDs, and any other debugging information. For crashing bugs:

  • Win32: If you receive a Dr. Watson error, please note the type of the crash, and the module that the application crashed in. (e.g. access violation in mozilla.exe)
  • Mac OS: If you're running MacsBug, please provide the results of a how and an sc.
  • Unix: Please provide a minimized stack trace, which can be generated by typing gdb mozilla core into a shell prompt.
      • MACSBUG STACK CRAWL OF CRASH (Mac OS)

Calling chain using A6/R1 links Back chain ISA Caller 00000000 PPC 0BA85E74 03AEFD80 PPC 0B742248 03AEFD30 PPC 0B50FddC NSGetFactory+027FC PowerPC unmapped memory exception at 0B512BD0 NSGetFactory+055F0

You're done!

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

(The Mozilla QA Bug Writing Guidelines were originally written by Eli Goldberg. Thanks to Claudius Gayle, Jan Leger, Peter Mock, Chris Pratt, Chris Yeh and Felix Miata for contributing to this document. Additional suggestions welcome.)

Revision Source

<h2 name="Why_You_Should_Read_This">Why You Should Read This</h2>
<p>The Mozilla bug tracking system ([http://bugzilla.mozilla.org Bugzilla) allows any interested individuals on the Internet to directly report and track bugs in mozilla.org open-source projects like the Mozilla Application Suite or Mozilla Firefox.
Like you, Mozilla QA (Quality Assurance) wants your bug reports to result in bug fixes; the more effectively a bug is reported, the more likely that an engineer will actually fix it.
By following these guidelines, you can help ensure that your bugs stay at the top of the Mozilla engineers' heap, and get fixed. <a class="external" href="http://bugzilla.mozilla.org">Bugzilla</a> is the preferred method of submitting a bug - the linked entry form incorporates parts of these guidelines.
</p>
<h2 name="How_to_Write_a_Useful_Bug_Report">How to Write a Useful Bug Report</h2>
<p>Useful bug reports are ones that get bugs fixed. A useful bug report normally has two qualities:
</p>
<ol><li> Reproducible. If an engineer can't see it or conclusively prove that it exists, the engineer will probably stamp it WORKSFORME or INVALID, and move on to the next bug. Every relevant detail you can provide helps.
</li><li> Specific. The quicker the engineer can isolate the issue to a specific problem, the more likely it'll be expediently fixed. If you're crashing on a site, please take the time to isolate what on the page is triggering the crash, and include it as an HTML snippet in the bug report if possible. (Specific bugs have the added bonus of remaining relevant when an engineer actually gets to them; in a rapidly changing web, a bug report of "foo.com crashes my browser" becomes meaningless after the site experiences a half-dozen redesigns and hundreds of content changes.)
</li></ol>
<p>Let's say you crash at foo.com, and want to write up a bug report:
</p><p><b>BAD</b>: "My browser crashed. I think I was on foo.com. I think that this is a really bad problem and you should fix it or else nobody will use your browser. By the way, my sister thinks your icons really suck. Oh, and my mom's home page doesn't look right, either, it's all messed up. Thx 4 fixing theze bugz."
<b>GOOD</b>: "I crashed each time when I went to foo.com, using Mozilla on a Win NT 4.0 (Service Pack 5) system. The build ID is 20030609. I also rebooted into Linux, and reproduced this problem using the 20030608 Linux build.
Mozilla 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 Mozilla reproducibly, unless you remove the "border=0" attribute:
&lt;IMG SRC="http://foo.com/images/topics/topicfoos.gif" width=34 height=44 border=0 alt="News"&gt; 
</p><p>If your problem is Mozilla crashing, Talkback data is very helpful to engineers trying to diagnose the problem. If you can consistently reproduce the crash, please download a build with Talkback and install it. Then, do what is necessary to reproduce the crash, and follow the instructions for sending crash data to the server. Lastly, run the program components/talkback.exe (Win32) or components/talkback/talkback (Unix) and find your "Incident ID". Include this with the bug report. Please don't paste the raw Talkback data into your bug.
We'd also recommend reviewing a few of the better bug reports, such as 2683, 3092 or 4044. Bug submissions that do not meet these "Useful Bug Report" criteria tend to be investigated on a time-available basis, if investigated at all.
</p><p>How to Enter your Useful Bug Report into Bugzilla
</p><p>Before you enter your bug, you need to make sure it has not been previously reported. There is a tutorial on the best ways of doing this.
Next, be sure that you've reproduced your bug using a build released within the past three days. Our development process moves at lightning speed, and the bug you've found may already have been fixed. (Nightly builds can be downloaded from the mozilla.org binaries page.)
If you've discovered a new bug using a current build, report it in the guided Bugzilla entry form.
</p><p>1. Are you sure you don't want to use the guided form? :-) You won't have to read the rest of this page if you do...
2. OK, then. From the Bugzilla main page (http://bugzilla.mozilla.org), choose "Enter a new bug".
3. Select the product that you've found a bug in.
4. If you haven't logged into Bugzilla already, you'll need to enter your email address, password, and press the "Login" button. (If you don't yet have a password, enter your email address below and press the "Submit Request" button instead. You'll receive an email message with your password shortly.)
</p><p>Now, fill out the form. Here's what it all means:
</p><p>Where did you find the bug?
</p><p>Product: In which product did you find the bug? You just filled this out on the last page.
Version: In which product version did you find the bug? We're not yet using this field. Just leave the default value as you found it. ;)
Component: In which component does the bug exist?
Bugzilla requires that you select a component to enter a bug. (If they all look meaningless, click on the Component link, which links to descriptions of each component, to help you make the best choice.)
Platform: On which hardware platform did you find this bug? (e.g. Macintosh, SGI, Sun, PC.)
If you know the bug happens on all hardware platforms, choose 'All'. Otherwise, select the platform that you found the bug on, or "Other" if your platform isn't listed.
OS: On which Operating System (OS) did you find this bug? (e.g. Linux, Windows NT, Mac OS X) If you know the bug happens on all OSs, choose 'All'. Otherwise, select the OS that you found the bug on, or "Other" if your OS isn't listed.
</p><p>How important is the bug?
</p><p>Severity: How damaging is the bug? This item defaults to 'normal'. (To determine the most appropriate severity for a particular bug, click on the Severity link for a full explanation of each choice, from Critical to Enhancement.)
</p><p>Who will be following up on the bug?
</p><p>Assigned To: Which engineer should be responsible for fixing this bug?
Bugzilla will automatically assign the bug to a default engineer upon submitting a bug report; the text box exists to allow you to manually assign it to a different engineer. (To see the list of default engineers for each component, click on the Component link.)
Cc: Who else should receive e-mail updates on changes to this bug? List the full e-mail addresses of other individuals who should receive an e-mail update upon every change to the bug report. You can enter as many e-mail addresses as you'd like; e-mail addresses must be separated by commas, with no spaces between the addresses.
</p><p>You would not normally change either of these fields from their default values.
</p><p>What else can you tell the engineer about the bug?
</p><p>URL: On what URL did you discover this bug? If you encountered the bug on a particular URL, please provide it (or, them) here. If you've isolated the bug to a specific HTML snippet, please also provide a URL for that, too or, preferably, return to the bug after you've submitted it and add the HTML snippet as an attachment.
</p><p>Summary: How would you describe the bug, in approximately 60 or fewer characters? A good summary should quickly and uniquely identify a bug report. Otherwise, developers cannot meaningfully query by bug summary, and will often fail to pay attention to your bug report when reviewing a 10 page bug list. Think of it as a "title".
A summary of "Drag-scrolling any web page crashes Mac OS X builds" is a useful title. "Crash" or "Drag Crash" would be examples of a bad title.
</p><p>Description: What else can you tell the engineer about this bug? Please provide as detailed of a problem diagnosis in this field as possible, including as much as possible of the following information:
</p><p>Overview Description: More detailed expansion of summary.
Drag-selecting any page crashes Mac OS X builds in NSGetFactory
Steps to Reproduce: The minimal set of steps necessary to trigger the bug. Include any special setup steps.
1) View any web page. (I used the default sample page, resource:/res/samples/test0.html)
2) Drag-select the page. (Specifically, while holding down the mouse button, drag the mouse pointer downwards from any point in the browser's content region to the bottom of the browser's content region.)
</p><p>Actual Results: What the application did after performing the above steps.
</p><p>The application crashed. Stacktrace appended below from gdb.
</p><p>Expected Results: What the application should have done, were the bug not present. The window should scroll downwards. Scrolled content should be selected. (Or, at least, the application should not crash.)
</p><p>Build Date &amp; Platform: Date and platform of the build that you first encountered the bug in. (The build date can be found as part of the window title, in YYYYMMddHH format.)
2003060709 installer build on Mac OS X
</p><p>Additional Builds and Platforms: Whether or not the bug takes place on other platforms or browsers.
</p><p>- Occurs On Seamonkey (20030605 build on Windows 2000)
- Doesn't Occur On Seamonkey (20030602 build on Suse Linux), IE 6 (Windows XP), Netscape Navigator 4.5 (Mac OS)
Additional Information: Minimized HTML snippets, Talkback crash IDs, and any other debugging information. For crashing bugs:
</p>
<ul><li> Win32: If you receive a Dr. Watson error, please note the type of the crash, and the module that the application crashed in. (e.g. access violation in mozilla.exe)
</li><li> Mac OS: If you're running MacsBug, please provide the results of a how and an sc.
</li><li> Unix: Please provide a minimized stack trace, which can be generated by typing gdb mozilla core into a shell prompt.
</li></ul>
<ul><li><ul><li><ul><li> MACSBUG STACK CRAWL OF CRASH (Mac OS)
</li></ul>
</li></ul>
</li></ul>
<p>Calling chain using A6/R1 links
Back chain ISA Caller
00000000 PPC 0BA85E74
03AEFD80 PPC 0B742248
03AEFD30 PPC 0B50FddC NSGetFactory+027FC
PowerPC unmapped memory exception at
0B512BD0 NSGetFactory+055F0
</p><p>You're done!
</p><p>After double-checking your entries for any possible errors, press the "Commit" button, and your bug report will be part of the Bugzilla database.
</p><p>(The Mozilla QA Bug Writing Guidelines were originally written by Eli Goldberg. Thanks to Claudius Gayle, Jan Leger, Peter Mock, Chris Pratt, Chris Yeh and Felix Miata for contributing to this document. Additional suggestions  welcome.)
</p>
Revert to this revision