<p>Simply put, the more effectively you report a bug, the more
likely an engineer will actually fix it.</p>
<BLOCKQUOTE>
<p>These guidelines are a general
<P>Simply put, the more effectively you report a bug, the more likely an engineer
tutorial to teach novice and intermediate bug reporters how to compose effective bug reports. Not every sentence may precisely apply to
will actually fix it. <BR>
your software project.</p>
<AHREF="http://bugzilla.mozilla.org"><BR>
</blockquote>
</A>These bug writing guidelines are an attempt at a general tutorial on writing
effective bug reports for novice bug writers; not every sentence may precisely apply
<h3>How to Write a Useful Bug Report</h3>
to your software project.
<blockquote>
</BLOCKQUOTE>
<p>Useful bug reports are ones that get bugs fixed. A useful bug
report normally has two qualities:</p>
<P><FONTSIZE="4"><B><BR>
How to Write a Useful Bug Report</B></FONT>
<ol>
<li><b>Reproducible.</b> If an engineer can't see the bug herself to prove that it exists, she'll probably stamp your bug report "WORKSFORME" or "INVALID" and move on to the next bug. Every detail you can provide helps.<br>
<br>
<BLOCKQUOTE>
</li>
<P>Useful bug reports are ones that get bugs fixed. A useful bug report normally
has two qualities:
<li><b>Specific.</b> The quicker the engineer can isolate the bug
to a specific area, the more likely she'll expediently fix it.
<OL>
(If a programmer or tester has to decypher a bug, they may spend
<LI><B>Reproducible.</B> If an engineer can't see it or conclusively prove that it
more time cursing the submitter than solving the problem.)
exists, the engineer will probably stamp it "WORKSFORME" or "INVALID",
<br>
and move on to the next bug. Every detail you can provide helps. <BR>
<br>
<BR>
[ <ahref="#tips"name="Anchor">Tell Me More</a> ]
</li>
<LI><B>Specific.</B> The quicker the engineer can isolate the issue to a specific
</ol>
problem, the more likely it'll be expediently fixed.<B></B>(If a programmer or tester
has to decypher a bug, they spend more time cursing the submitter than fixing or
<p>Let's say the application you're testing is a web browser. You
testing the problem.)
crash at foo.com, and want to write up a bug report:</p>
</OL>
<blockquote>
<P>Let's say the application you're testing is a web browser. You crash at foo.com,
<p><b>BAD:</b> "My browser crashed. I think I was on www.foo.com. I play golf with Bill Gates, so you better fix this problem, or I'll report you to him. By the way, your Back icon looks like a squashed rodent. UGGGLY. And my grandmother's home page is all messed up in your browser. Thx 4 UR help."
and want to write up a bug report:
</p>
<BLOCKQUOTE>
<p>
<P><B>BAD:</B>"My browser crashed. I think I was on foo.com. My computer uses
<b>GOOD:</b> "I crashed each time I went to www.foo.com, using
Windows. I think that this is a really bad problem and you should fix it now. By
the 2002-02-25 build on a Windows 2000 system. I also
the way, your icons really suck. Nobody will use your software if you keep those
rebooted into Linux, and reproduced this problem using the 2002-02-24
ugly icons. Oh, and my grandmother's home page doesn't look right, either, it's all
Linux build.
messed up. Good luck."<BR>
</p>
<BR>
<B>GOOD: </B>"I crashed each time when I went to foo.com, using the 10.28.99
<p>
build on a Win NT 4.0 (Service Pack 5) system. I also rebooted into Linux, and reproduced
It again crashed each time upon drawing the Foo banner at the top
this problem using the 10.28.99 Linux build.<BR>
of the page. I broke apart the page, and discovered that the
<BR>
following image link will crash the application reproducibly,
It again crashed each time upon drawing the Foo banner at the top of the page. I
unless you remove the "border=0" attribute:
broke apart the page, and discovered that the following image link will crash the
</p>
application reproducibly, unless you remove the "border=0" attribute:<BR>
<h3>How to Enter your Useful Bug Report into Bugzilla:</h3>
<P><FONTSIZE="4"><B><BR>
<BR>
<blockquote>
How to Enter your Useful Bug Report into Bugzilla</B>:</FONT>
<p>Before you enter your bug, use Bugzilla's
<ahref="query.cgi">search page</a> to determine whether the defect you've discovered is a known, already-reported bug. If your bug is the 37th duplicate of a known issue, you're more likely to annoy the engineer. (Annoyed
engineers fix fewer bugs.)
<BLOCKQUOTE>
</p>
<P>Before you enter your bug, use the Bugzilla Query Page to determine whether the
defect you've discovered is a known bug, and has already been reported. (If your
<p>
bug is the 37th duplicate of a known issue, you're more likely to annoy the engineer.
Next, be sure to reproduce your bug using a recent
Annoyed engineers fix fewer bugs.)<BR>
build. Engineers tend to be most interested in problems affecting
<BR>
the code base that they're actively working on. After all, the bug you're reporting
Next, be sure that you've reproduced your bug using a recent build. (Engineers tend
may already be fixed.
to be most interested in problems afflicting the code base that they're actively
working on, rather than those in a code base that's hundreds of bug fixes obsolete.)<BR>
</p>
<BR>
If you've discovered a new bug using a current build, report it in Bugzilla:
<p>
If you've discovered a new bug using a current build, report it in
</BLOCKQUOTE>
Bugzilla:
</p>
<OL>
<ol>
<OL>
<li>From your Bugzilla main page, choose
<LI>From your Bugzilla main page, choose "Enter a new bug".
"<ahref="enter_bug.cgi">Enter a new bug</a>".</li>
<LI>Select the product that you've found a bug in.
<LI>Enter your E-mail address, Password, and press the "Login" button.
<li>Select the product that you've found a bug in.</li>
(If you don't yet have a password, leave the password text box empty, and press the
"E-mail me a password" button instead. You'll receive an E-mail message
<li>Enter your e-mail address, password, and press the "Login"
with your password shortly.)
button. (If you don't yet have a password, leave the password field empty,
</OL>
and press the "E-mail me a password" button instead.
<P>Now, fill out the form. Here's what it all means:
You'll quickly receive an e-mail message with your password.)</li>
</OL>
</ol>
<p>Now, fill out the form. Here's what it all means:</p>
<BLOCKQUOTE>
<p><b>Where did you find the bug?</b></p>
<P><B>Where did you find the bug?</B>
<blockquote>
<BLOCKQUOTE>
<p><b>Product: In which product did you find the bug?</b><br>
<P><B>Product: In which product did you find the bug?</B><BR>
You just specified this on the last page, so you can't edit it here.</p>
You just filled this out on the last page.</P>
<P><B>Version: In which product version did you find the bug?</B><BR>
<p><b>Version: In which product version did you find the
If applicable.</P>
bug?</b><br>
<P><B>Component: In which component does the bug exist?</B><BR>
(If applicable)</p>
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
<p><b>Component: In which component does the bug exist?</b><br>
you make the best choice.)</P>
Bugzilla requires that you select a component to enter a bug. (Not sure which to choose?
<P><B>Platform: On which hardware platform did you find this bug?</B><FONTSIZE="2"><B>
Click on the Component link. You'll see a description of each component, to help you make the best choice.)</p>
</B>(e.g. Macintosh, SGI, Sun, PC.) </FONT><BR>
If you know the bug happens on all hardware platforms, choose 'All'. Otherwise, select
<p><b>OS: On which Operating System (OS) did you find this bug?</b>
the platform that you found the bug on, or "Other" if your platform isn't
(e.g. Linux, Windows 2000, Mac OS 9.)<br>
listed.</P>
If you know the bug happens on all OSs, choose 'All'. Otherwise,
<P><B>OS: On which Operating System (OS) did you find this bug?</B><FONTSIZE="2">(e.g.
select the OS that you found the bug on, or "Other" if your OS
Linux, Windows NT, Mac OS 8.5.)</FONT><BR>
isn't listed.</p>
If you know the bug happens on all OSs, choose 'All'. Otherwise, select the OS that
</blockquote>
you found the bug on, or "Other" if your OS isn't listed.</P>
<p><b>How important is the bug?</b></p>
</BLOCKQUOTE>
<P><B><BR>
<blockquote>
How important is the bug?</B>
<p><b>Severity: How damaging is the bug?</b><br>
This item defaults to 'normal'. If you're not sure what severity your bug deserves, click on the Severity link.
<BLOCKQUOTE>
You'll see a description of each severity rating. <br>
<P><B>Severity: How damaging is the bug?</B><BR>
</p>
This item defaults to 'normal'. (To determine the most appropriate severity for a
</blockquote>
particular bug, click on the Severity link for a full explanation of each choice,
from Critical to Enhancement.)
<p><b>Who will be following up on the bug?</b></p>
</BLOCKQUOTE>
<blockquote>
<P><B><BR>
<p><b>Assigned To: Which engineer should be responsible for fixing
Who will be following up on the bug?</B>
this bug?</b><br>
Bugzilla will automatically assign the bug to a default engineer
<BLOCKQUOTE>
upon submitting a bug report. If you'd prefer to directly assign the bug to
<P><B>Assigned To: Which engineer should be responsible for fixing this bug?</B><BR>
someone else, enter their e-mail address into this field. (To see the list of
Bugzilla will automatically assign the bug to a default engineer upon submitting
default engineers for each component, click on the Component
a bug report; the text box exists to allow you to manually assign it to a different
link.)</p>
engineer. (To see the list of default engineers for each component, click on the
Component link.)</P>
<p><b>Cc: Who else should receive e-mail updates on changes to this
<P><B>Cc: Who else should receive e-mail updates on changes to this bug? </B><BR>
bug?</b><br>
List the full e-mail addresses of other individuals who should receive an e-mail
List the full e-mail addresses of other individuals who should
update upon every change to the bug report. You can enter as many e-mail addresses
receive an e-mail update upon every change to the bug report. You
as you'd like; e-mail addresses must be separated by commas, with no spaces between
can enter as many e-mail addresses as you'd like, separated by spaces or commas, as long as those
the addresses.
people have Bugzilla accounts.</p>
</blockquote>
</BLOCKQUOTE>
<P><B><BR>
<p><b>What else can you tell the engineer about the bug?</b></p>
What else can you tell the engineer about the bug?</B></P>
<blockquote>
<BLOCKQUOTE>
<P><B>URL: On what URL did you discover this bug?</B><BR>
<p><b>Summary:</b><b>How would you describe the bug, in
If you encountered the bug on a particular URL, please provide it (or, them) here.
approximately 60 or fewer characters?</b><br>
If you've isolated the bug to a specific HTML snippet, please also provide a URL
A good summary should <b>quickly and uniquely identify a bug
for that, too.</P>
report</b>. Otherwise, an engineer cannot meaningfully identify
your bug by its summary, and will often fail to pay attention to
<P><B>Summary:</B><B>How would you describe the bug, in approximately 60 or fewer
your bug report when skimming through a 10 page bug list.<br>
characters?</B><BR>
<br>
A good summary should <U>quickly and uniquely identify a bug report</U>. Otherwise,
A useful summary might be
developers cannot meaningfully query by bug summary, and will often fail to pay attention
"<tt>PCMCIA install fails on Tosh Tecra 780DVD w/ 3c589C</tt>".
to your bug report when reviewing a 10 page bug list.<BR>
"<tt>Software fails</tt>" or "<tt>install problem</tt>" would be
<BR>
examples of a bad summary.<br>
A summary of "PCMCIA install fails on Tosh Tecra 780DVD w/ 3c589C" is a
<br>
useful title. "Software fails" or "install problem" would be
[ <ahref="#summary">Tell Me More</a> ]<br>
examples of a bad title.</P>
<br>
<b>Description: </b><br>
<P><BR>
Please provide a detailed problem report in this field.
<B>Description: What else can you tell the engineer about this bug? </B><BR>
Your bug's recipients will most likely expect the following information:</p>
Please provide as detailed of a problem diagnosis in this field as possible. <BR>
<BR>
<blockquote>
Where applicable, using the following bug report template will help ensure that all
<p><b>Overview Description:</b> More detailed expansion of
relevant information comes through:
summary.</p>
<BLOCKQUOTE>
<blockquote>
<P><B>Overview Description:</B> More detailed expansion of summary.
<pre>
Drag-selecting any page crashes Mac builds in NSGetFactory
<BLOCKQUOTE>
</pre>
<PRE><FONTSIZE="2">Drag-selecting any page crashes Mac builds in NSGetFactory</FONT></PRE>
</blockquote>
</BLOCKQUOTE>
<p><b>Steps to Reproduce:</b> Minimized, easy-to-follow steps that will
<P><B>Steps to Reproduce: </B>The minimal set of steps necessary to trigger the bug.
trigger the bug. Include any special setup steps.</p>
Include any special setup steps.
<blockquote>
<BLOCKQUOTE>
<pre>
<PRE><FONTSIZE="2">1) View any web page. (I used the default sample page,
1) View any web page. (I used the default sample page,
resource:/res/samples/test0.html)
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
2) Drag-select the page. (Specifically, while holding down
the browser's content region to the bottom of the browser's
the mouse button, drag the mouse pointer downwards from any
content region.)</FONT></PRE>
point in the browser's content region to the bottom of the
browser's content region.)
</BLOCKQUOTE>
</pre>
<P><B>Actual Results:</B> What the application did after performing the above steps.
</blockquote>
<BLOCKQUOTE>
<b>Actual Results:</b> What the application did after performing
<PRE><FONTSIZE="2">The application crashed. Stack crawl appended below from MacsBug.</FONT></PRE>
the above steps.
</BLOCKQUOTE>
<blockquote>
<P><B>Expected Results:</B> What the application should have done, were the bug not
<pre>
present.
The application crashed. Stack crawl appended below from MacsBug.
</pre>
<BLOCKQUOTE>
</blockquote>
<PRE><FONTSIZE="2">The window should scroll downwards. Scrolled content should
be selected. (Or, at least, the application should not crash.)</FONT></PRE>
<p><b>Expected Results:</b> What the application should have done,
were the bug not present.</p>
</BLOCKQUOTE>
<P><B>Build Date & Platform:</B> Date and platform of the build that you first
<blockquote>
encountered the bug in.
<pre>
The window should scroll downwards. Scrolled content should be selected.
<BLOCKQUOTE>
(Or, at least, the application should not crash.)
<PRE><FONTSIZE="2">11/2/99 build on Mac OS (Checked Viewer & Apprunner)</FONT></PRE>
</pre>
</blockquote>
</BLOCKQUOTE>
<P><B>Additional Builds and Platforms:</B> Whether or not the bug takes place on
<p><b>Build Date & Platform:</b> Date and platform of the build
other platforms or browsers.
that you first encountered the bug in.</p>
<BLOCKQUOTE>
<blockquote>
<PRE><FONTSIZE="2"> - Occurs On
<pre>
Seamonkey (11/2/99 build on Windows NT 4.0)
Build 2002-03-15 on Mac OS 9.0
</pre>
- Doesn't Occur On
</blockquote>
Seamonkey (11/4/99 build on Red Hat Linux; feature not supported)
Internet Explorer 5.0 (RTM build on Windows NT 4.0)
<p><b>Additional Builds and Platforms:</b> Whether or not the bug
Netscape Communicator 4.5 (RTM build on Mac OS)</FONT>
takes place on other platforms (or browsers, if applicable).</p>
</PRE>
<blockquote>
</BLOCKQUOTE>
<pre>
<P><B>Additional Information:</B> Any other debugging information. For crashing bugs:
- Also Occurs On
Mozilla (2002-03-15 build on Windows NT 4.0)
<UL>
<LI><B>Win32:</B> if you receive a Dr. Watson error, please note the type of the
- Doesn't Occur On
crash, and the module that the application crashed in. (e.g. access violation in
Mozilla (2002-03-15 build on Red Hat Linux; feature not supported)
apprunner.exe)
Internet Explorer 5.0 (shipping build on Windows NT 4.0)
<LI><B>Mac OS:</B> if you're running MacsBug, please provide the results of a <B><TT>how</TT></B>
Netscape Communicator 4.5 (shipping build on Mac OS 9.0)
and an <B><TT>sc</TT></B>.
</pre>
<LI><B>Unix: </B>please provide a minimized stack trace, which can be generated by
</blockquote>
typing <B><TT>gdb apprunner core</TT></B> into a shell prompt.
</UL>
<p><b>Additional Information:</b> Any other debugging information.
For crashing bugs:</p>
<BLOCKQUOTE>
<ul>
<P>
<li><b>Win32:</b> if you receive a Dr. Watson error, please note
<PRE><FONTSIZE="2">*** MACSBUG STACK CRAWL OF CRASH (Mac OS)
the type of the crash, and the module that the application crashed
in. (e.g. access violation in apprunner.exe)</li>
<li><b>Mac OS:</b> if you're running MacsBug, please provide the
results of a <b>how</b> and an <b>sc</b>:</li>
</ul>
<blockquote>
<pre>
*** MACSBUG STACK CRAWL OF CRASH (Mac OS)
Calling chain using A6/R1 links
Calling chain using A6/R1 links
Back chain ISA Caller
Back chain ISA Caller
00000000 PPC 0BA85E74
00000000 PPC 0BA85E74
03AEFD80 PPC 0B742248
03AEFD80 PPC 0B742248
03AEFD30 PPC 0B50FDDC NSGetFactory+027FC
03AEFD30 PPC 0B50FDDC NSGetFactory+027FC
PowerPC unmapped memory exception at 0B512BD0 NSGetFactory+055F0</FONT></PRE>
PowerPC unmapped memory exception at 0B512BD0 NSGetFactory+055F0
</pre>
</BLOCKQUOTE>
</blockquote>
</blockquote>
</BLOCKQUOTE>
</blockquote>
</BLOCKQUOTE>
<p>You're done!<br>
<P>You're done! <BR>
<br>
<BR>
After double-checking your entries for any possible errors, press
After double-checking your entries for any possible errors, press the "Commit"
the "Commit" button, and your bug report will now be in the
button, and your bug report will now be in the Bugzilla database.<BR>
Bugzilla database.<br>
<I><BR>
</p>
<BR>
</blockquote>
</I><FONTSIZE="2">(Thanks to Claudius Gayle, Peter Mock, Chris Pratt, Tom Schutter,
and Chris Yeh for contributing to this document. Constructive </FONT><AHREF="mailto:eli@prometheus-music.com"><FONT
