mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-11-08 04:27:37 +00:00
10422610d8
transitional compliant Original patch by chema@ximian.com, modified/extended by bbaetz@student.usyd.edu.au r=gerv, justdave
393 lines
12 KiB
HTML
393 lines
12 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
|
|
<title>Bug Writing Guidelines</title>
|
|
</head>
|
|
<body>
|
|
<center>
|
|
<h1>Bug Writing Guidelines</h1>
|
|
</center>
|
|
|
|
<h3>Why You Should Read This</h3>
|
|
|
|
<blockquote>
|
|
<p>Simply put, the more effectively you report a bug, the more
|
|
likely an engineer will actually fix it.</p>
|
|
|
|
<p>These guidelines are a general
|
|
tutorial to teach novice and intermediate bug reporters how to compose effective bug reports. Not every sentence may precisely apply to
|
|
your software project.</p>
|
|
</blockquote>
|
|
|
|
<h3>How to Write a Useful Bug Report</h3>
|
|
|
|
<blockquote>
|
|
<p>Useful bug reports are ones that get bugs fixed. A useful bug
|
|
report normally has two qualities:</p>
|
|
|
|
<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>
|
|
</li>
|
|
|
|
<li><b>Specific.</b> The quicker the engineer can isolate the bug
|
|
to a specific area, the more likely she'll expediently fix it.
|
|
(If a programmer or tester has to decypher a bug, they may spend
|
|
more time cursing the submitter than solving the problem.)
|
|
<br>
|
|
<br>
|
|
[ <a href="#tips" name="Anchor">Tell Me More</a> ]
|
|
</li>
|
|
</ol>
|
|
|
|
<p>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:</p>
|
|
|
|
<blockquote>
|
|
<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."
|
|
</p>
|
|
|
|
<p>
|
|
<b>GOOD:</b> "I crashed each time I went to www.foo.com, using
|
|
the 2002-02-25 build on a Windows 2000 system. I also
|
|
rebooted into Linux, and reproduced this problem using the 2002-02-24
|
|
Linux build.
|
|
</p>
|
|
|
|
<p>
|
|
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:
|
|
</p>
|
|
|
|
<p>
|
|
<tt><IMG SRC="http://www.foo.com/images/topics/topicfoos.gif"
|
|
width="34" height="44" border="0" alt="News"></tt>
|
|
</p>
|
|
</blockquote>
|
|
</blockquote>
|
|
|
|
<h3>How to Enter your Useful Bug Report into Bugzilla:</h3>
|
|
|
|
<blockquote>
|
|
<p>Before you enter your bug, use Bugzilla's
|
|
<a href="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.)
|
|
</p>
|
|
|
|
<p>
|
|
Next, be sure to reproduce your bug using a recent
|
|
build. 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.
|
|
|
|
</p>
|
|
|
|
<p>
|
|
If you've discovered a new bug using a current build, report it in
|
|
Bugzilla:
|
|
</p>
|
|
|
|
<ol>
|
|
<li>From your Bugzilla main page, choose
|
|
"<a href="enter_bug.cgi">Enter a new bug</a>".</li>
|
|
|
|
<li>Select the product that you've found a bug in.</li>
|
|
|
|
<li>Enter your e-mail address, password, and press the "Login"
|
|
button. (If you don't yet have a password, leave the password field empty,
|
|
and press the "E-mail me a password" button instead.
|
|
You'll quickly receive an e-mail message with your password.)</li>
|
|
</ol>
|
|
|
|
<p>Now, fill out the form. Here's what it all means:</p>
|
|
|
|
<p><b>Where did you find the bug?</b></p>
|
|
|
|
<blockquote>
|
|
<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>
|
|
|
|
<p><b>Version: In which product version did you find the
|
|
bug?</b><br>
|
|
(If applicable)</p>
|
|
|
|
<p><b>Component: In which component does the bug exist?</b><br>
|
|
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.)</p>
|
|
|
|
<p><b>OS: On which Operating System (OS) did you find this bug?</b>
|
|
(e.g. Linux, Windows 2000, Mac OS 9.)<br>
|
|
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>
|
|
</blockquote>
|
|
|
|
<p><b>How important is the bug?</b></p>
|
|
|
|
<blockquote>
|
|
<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.
|
|
You'll see a description of each severity rating. <br>
|
|
</p>
|
|
</blockquote>
|
|
|
|
<p><b>Who will be following up on the bug?</b></p>
|
|
|
|
<blockquote>
|
|
<p><b>Assigned To: Which engineer should be responsible for fixing
|
|
this bug?</b><br>
|
|
Bugzilla will automatically assign the bug to a default engineer
|
|
upon submitting a bug report. If you'd prefer to directly assign the bug to
|
|
someone else, enter their e-mail address into this field. (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
|
|
bug?</b><br>
|
|
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, separated by spaces or commas, as long as those
|
|
people have Bugzilla accounts.</p>
|
|
</blockquote>
|
|
|
|
<p><b>What else can you tell the engineer about the bug?</b></p>
|
|
|
|
<blockquote>
|
|
|
|
<p><b>Summary:</b> <b>How would you describe the bug, in
|
|
approximately 60 or fewer characters?</b><br>
|
|
A good summary should <b>quickly and uniquely identify a bug
|
|
report</b>. Otherwise, an engineer cannot meaningfully identify
|
|
your bug by its summary, and will often fail to pay attention to
|
|
your bug report when skimming through a 10 page bug list.<br>
|
|
<br>
|
|
A useful summary might be
|
|
"<tt>PCMCIA install fails on Tosh Tecra 780DVD w/ 3c589C</tt>".
|
|
"<tt>Software fails</tt>" or "<tt>install problem</tt>" would be
|
|
examples of a bad summary.<br>
|
|
<br>
|
|
[ <a href="#summary">Tell Me More</a> ]<br>
|
|
<br>
|
|
<b>Description: </b><br>
|
|
Please provide a detailed problem report in this field.
|
|
Your bug's recipients will most likely expect the following information:</p>
|
|
|
|
<blockquote>
|
|
<p><b>Overview Description:</b> More detailed expansion of
|
|
summary.</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
Drag-selecting any page crashes Mac builds in NSGetFactory
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p><b>Steps to Reproduce:</b> Minimized, easy-to-follow steps that will
|
|
trigger the bug. Include any special setup steps.</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
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.)
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>
|
|
<b>Actual Results:</b> What the application did after performing
|
|
the above steps.
|
|
</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
The application crashed. Stack crawl appended below from MacsBug.
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p><b>Expected Results:</b> What the application should have done,
|
|
were the bug not present.</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
The window should scroll downwards. Scrolled content should be selected.
|
|
(Or, at least, the application should not crash.)
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p><b>Build Date & Platform:</b> Date and platform of the build
|
|
that you first encountered the bug in.</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
Build 2002-03-15 on Mac OS 9.0
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p><b>Additional Builds and Platforms:</b> Whether or not the bug
|
|
takes place on other platforms (or browsers, if applicable).</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
- Also Occurs On
|
|
Mozilla (2002-03-15 build on Windows NT 4.0)
|
|
|
|
- Doesn't Occur On
|
|
Mozilla (2002-03-15 build on Red Hat Linux; feature not supported)
|
|
Internet Explorer 5.0 (shipping build on Windows NT 4.0)
|
|
Netscape Communicator 4.5 (shipping build on Mac OS 9.0)
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p><b>Additional Information:</b> Any other debugging information.
|
|
For crashing bugs:</p>
|
|
|
|
<ul>
|
|
<li><b>Win32:</b> 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 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
|
|
Back chain ISA Caller
|
|
00000000 PPC 0BA85E74
|
|
03AEFD80 PPC 0B742248
|
|
03AEFD30 PPC 0B50FDDC NSGetFactory+027FC
|
|
PowerPC unmapped memory exception at 0B512BD0 NSGetFactory+055F0
|
|
</pre>
|
|
</blockquote>
|
|
</blockquote>
|
|
</blockquote>
|
|
|
|
<p>You're done!<br>
|
|
<br>
|
|
After double-checking your entries for any possible errors, press
|
|
the "Commit" button, and your bug report will now be in the
|
|
Bugzilla database.<br>
|
|
</p>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<h3>More Information on Writing Good Bugs</h3>
|
|
|
|
<blockquote>
|
|
<p><b><a name="tips"></a> 1. General Tips for a Useful Bug
|
|
Report</b>
|
|
</p>
|
|
|
|
<blockquote>
|
|
<p>
|
|
<b>Use an explicit structure, so your bug reports are easy to
|
|
skim.</b> Bug report users often need immediate access to specific
|
|
sections of your bug. If your Bugzilla installation supports the
|
|
Bugzilla Helper, use it.
|
|
</p>
|
|
|
|
<p>
|
|
<b>Avoid cuteness if it costs clarity.</b> Nobody will be laughing
|
|
at your funny bug title at 3:00 AM when they can't remember how to
|
|
find your bug.
|
|
</p>
|
|
|
|
<p>
|
|
<b>One bug per report.</b> 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.
|
|
</p>
|
|
|
|
<p>
|
|
<b>No bug is too trivial to report.</b> 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.<br>
|
|
</p>
|
|
</blockquote>
|
|
|
|
<p><b><a name="summary"></a>2. How and Why to Write Good Bug Summaries</b>
|
|
</p>
|
|
|
|
<blockquote>
|
|
<p><b>You want to make a good first impression on the bug
|
|
recipient.</b> 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?
|
|
</p>
|
|
|
|
<p>
|
|
Conversely, a vague bug summary like <tt>install problem</tt> forces anyone
|
|
reviewing installation bugs to waste time opening up your bug to
|
|
determine whether it matters.
|
|
</p>
|
|
|
|
<p>
|
|
<b>Your bug will often be searched by its summary.</b> 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.
|
|
</p>
|
|
|
|
<p>
|
|
For example, you'll find a bug titled "<tt>Dragging icons from List View to
|
|
gnome-terminal doesn't paste path</tt>" if you search on "List",
|
|
"terminal", or "path". Those search keywords wouldn't have found a
|
|
bug titled "<tt>Dragging icons
|
|
doesn't paste</tt>".
|
|
</p>
|
|
|
|
<p>
|
|
Ask yourself, "Would someone understand my bug from just this
|
|
summary?" If so, you've written a fine summary.
|
|
</p>
|
|
|
|
<p><b>Don't write titles like these:</b></p>
|
|
|
|
<ol>
|
|
<li>"Can't install" - Why can't you install? What happens when you
|
|
try to install?</li>
|
|
<li>"Severe Performance Problems" - ...and they occur when you do
|
|
what?</li>
|
|
<li>"back button does not work" - Ever? At all?</li>
|
|
</ol>
|
|
|
|
<p><b>Good bug titles:</b></p>
|
|
<ol>
|
|
<li>"1.0 upgrade installation fails if Mozilla M18 package present"
|
|
- Explains problem and the context.</li>
|
|
<li>"RPM 4 installer crashes if launched on Red Hat 6.2 (RPM 3)
|
|
system" - Explains what happens, and the context.</li>
|
|
</ol>
|
|
|
|
|
|
|
|
</blockquote>
|
|
</blockquote>
|
|
|
|
<p>(Written and maintained by
|
|
<a href="http://www.prometheus-music.com/eli">Eli Goldberg</a>. Claudius
|
|
Gayle, Gervase Markham, Peter Mock, Chris Pratt, Tom Schutter and Chris Yeh also
|
|
contributed significant changes. Constructive
|
|
<a href="mailto:eli@prometheus-music.com">suggestions</a> welcome.)</p>
|
|
|
|
</body>
|
|
</html>
|
|
|