348 lines
12 KiB
Cheetah
348 lines
12 KiB
Cheetah
[%# 1.0@bugzilla.org %]
|
|
[%# The contents of this file are subject to the Mozilla Public
|
|
# License Version 1.1 (the "License"); you may not use this file
|
|
# except in compliance with the License. You may obtain a copy of
|
|
# the License at http://www.mozilla.org/MPL/
|
|
#
|
|
# Software distributed under the License is distributed on an "AS
|
|
# IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
|
|
# implied. See the License for the specific language governing
|
|
# rights and limitations under the License.
|
|
#
|
|
# The Original Code is the Bugzilla Bug Tracking System.
|
|
#
|
|
# The Initial Developer of the Original Code is Netscape Communications
|
|
# Corporation. Portions created by Netscape are
|
|
# Copyright (C) 1998 Netscape Communications Corporation. All
|
|
# Rights Reserved.
|
|
#
|
|
# Contributor(s): Eli Goldberg <eli@prometheus-music.com>
|
|
# Gervase Markham <gerv@gerv.net>
|
|
# Vera Horiuchi
|
|
# Claudius Gayle
|
|
# Peter Mock
|
|
# Chris Pratt
|
|
# Tom Schutter
|
|
# Chris Yeh
|
|
#%]
|
|
|
|
[% PROCESS "global/field-descs.none.tmpl" %]
|
|
|
|
[% INCLUDE global/header.html.tmpl title = "$terms.Bug Writing Guidelines" %]
|
|
|
|
<h3>Contents</h3>
|
|
<ul>
|
|
<li><a href="#why">Why You Should Read This</a></li>
|
|
<li><a href="#useful">What Makes [% terms.aBug %] Report Useful?</a></li>
|
|
<li><a href="#before">Before You Start...</a></li>
|
|
<li><a href="#reporting">Reporting a New [% terms.Bug %]</a></li>
|
|
<li><a href="#more">More Information on Writing Good [% terms.Bugs %]</a></li>
|
|
</ul>
|
|
|
|
<h3><a name="why">Why You Should Read This</a></h3>
|
|
|
|
<blockquote>
|
|
<p>Simply put, the more effectively you report [% terms.abug %], the more
|
|
likely an engineer will actually fix it. This tutorial teaches novice and
|
|
intermediate [% terms.bug %] reporters how to write effective
|
|
[% terms.bug %] reports.</p>
|
|
</blockquote>
|
|
|
|
<h3><a name="useful">What Makes [% terms.aBug %] Report Useful?</a></h3>
|
|
|
|
<blockquote>
|
|
<p>Useful [% terms.bug %] reports get [% terms.bugs %] fixed.
|
|
A useful [% terms.bug %] report has two qualities:</p>
|
|
|
|
<ul>
|
|
<li><b>It's Reproducible.</b> Engineers usually prefer to fix [% terms.bugs %]
|
|
they can actually see. If an engineer can't reproduce the [% terms.bug %],
|
|
it'll probably be stamped "[% get_resolution("WORKSFORME") FILTER html %]" or
|
|
"[% get_resolution("INVALID") FILTER html %]".<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><b>It's Specific.</b> The quicker an engineer isolates the
|
|
[% terms.bug %] to a specific area, the more likely it'll be fixed. (If the
|
|
engineer must decipher your [% terms.bug %],
|
|
he or she will waste time cursing you instead.)<br>
|
|
</li>
|
|
</ul>
|
|
|
|
</blockquote>
|
|
|
|
<h3><a name="before">Before You Start...</a></h3>
|
|
|
|
<ol>
|
|
<li>Before you enter your [% terms.bug %], use [% terms.Bugzilla %]'s
|
|
<a href="query.cgi?format=specific">search page</a> to determine whether
|
|
your [% terms.bug %] is known.</li>
|
|
|
|
<li>Reproduce your [% terms.bug %] using a recent build.
|
|
Engineers tend to be most interested in problems affecting the code base
|
|
on which they're actively working. The [% terms.bug %] you're
|
|
reporting may already be fixed.</li>
|
|
</ol>
|
|
|
|
<blockquote>
|
|
Can't find your [% terms.bug %] in [% terms.Bugzilla %]? And you can reproduce
|
|
it in a recent build? Let's report it.
|
|
</blockquote>
|
|
|
|
<h3><a name="reporting">Reporting a New [% terms.Bug %]</a></h3>
|
|
|
|
<ol>
|
|
<li>From [% terms.Bugzilla %]'s main page, choose
|
|
"<a href="enter_bug.cgi">Enter a new [% terms.bug %]</a>".</li>
|
|
|
|
<li>Select the product in which you've found [% terms.abug %].</li>
|
|
|
|
<li>Log into [% terms.Bugzilla %].</li>
|
|
|
|
<li>Fill out the form. Here's what it all means:</li>
|
|
|
|
</ol>
|
|
|
|
|
|
<p><b>Where did you find the [% terms.bug %]?</b></p>
|
|
|
|
<blockquote>
|
|
<p><b>Product:</b> In which product did you find it?<br>
|
|
You just specified this on the last page, so you can't edit it
|
|
here.</p>
|
|
|
|
<p><b>Version:</b> In which product version did you find
|
|
it?<br>
|
|
(If applicable)</p>
|
|
|
|
<p><b>Component:</b> In which component does it
|
|
exist?<br>
|
|
[% terms.Bugzilla %] requires that you select a component to enter
|
|
[% terms.abug %]. (Click the Component link to see a description of each
|
|
component.)</p>
|
|
|
|
<p><b>OS:</b> On which operating system (OS) did you find
|
|
it?
|
|
(e.g. Linux, Windows XP, Mac OS X.)<br>
|
|
If the [% terms.bug %] happens on all operating systems, choose "All".
|
|
Otherwise, select the OS, or "Other" if your OS isn't listed.</p>
|
|
</blockquote>
|
|
|
|
<p><b>How important is the [% terms.bug %]?</b></p>
|
|
|
|
<blockquote>
|
|
<p><b>Severity:</b> How damaging is it?<br>
|
|
The default is 'normal' severity. (Click on the Severity link to see
|
|
a description of each severity rating.<br>
|
|
</p>
|
|
</blockquote>
|
|
|
|
<p><b>Who will be following up on the [% terms.bug %]?</b></p>
|
|
|
|
<blockquote>
|
|
<p><b>Assigned To:</b> Which engineer should be responsible for fixing
|
|
it?<br>
|
|
[% terms.Bugzilla %] automatically assigns the [% terms.bug %] to a
|
|
default engineer upon submitting [% terms.abug %] report. If you'd prefer
|
|
to directly assign the [% terms.bug %] to someone else, enter the person's
|
|
e-mail address. (To see the list of default engineers for each
|
|
component, click the Component link.)</p>
|
|
|
|
<p><b>Cc:</b> Who else should receive e-mail updates on changes to this
|
|
[% terms.bug %]?<br>
|
|
List the e-mail addresses of other people who should receive
|
|
an update whenever the [% terms.bug %] report changes. Enter as many e-mail
|
|
addresses as you'd like, separating them by spaces or
|
|
commas. Important: You can only enter people who have
|
|
[% terms.Bugzilla %] accounts.</p>
|
|
</blockquote>
|
|
|
|
<p><b>What else can you tell the engineer about the [% terms.bug %]?</b></p>
|
|
|
|
<blockquote>
|
|
<p><b>Summary:</b> How would you describe the [% terms.bug %], in
|
|
approximately 60 or fewer characters?<br>
|
|
A good summary should <b>quickly and uniquely identify [% terms.abug %]
|
|
report</b>. If an engineer can't identify your
|
|
[% terms.bug %] by its summary, it may be ignored when skimming through a
|
|
10-page list.<br>
|
|
<br>
|
|
A useful summary is "<tt>Cancelling a File Copy dialog crashes Nautilus</tt>".
|
|
Examples of bad summaries would be "<tt>Software crashes</tt>" or "<tt>copy problem</tt>".<br>
|
|
<br>
|
|
<b>Description:</b><br>
|
|
Provide a detailed problem report. [% terms.aBug %]'s recipients usually
|
|
expect the following information:</p>
|
|
|
|
<blockquote>
|
|
<p><b>Overview Description:</b> More detailed restatement 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 [% terms.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.
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p><b>Expected Results:</b> What the application should have done,
|
|
were the [% terms.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
|
|
in which you first encountered the [% terms.bug %].</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
Build 2006-08-10 on Mac OS 10.4.3
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p><b>Additional Builds and Platforms:</b> Whether or not
|
|
the [% terms.bug %] takes place on other platforms (or browsers,
|
|
if applicable).</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
- Doesn't Occur On Build 2006-08-10 on Windows XP Home (Service Pack 2)
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p><b>Additional Information:</b> Any other debugging information.
|
|
For crashing [% terms.bugs %]:</p>
|
|
|
|
<ul>
|
|
<li><b>Windows:</b> 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 X:</b> Attach the "Crash Reporter" log that appears upon crash.
|
|
Only include the section directly below the crashing thread, usually titled
|
|
"Thread 0 Crashed". Please do not paste the entire log!</li>
|
|
|
|
</ul>
|
|
|
|
</blockquote>
|
|
|
|
<p>You're done!<br>
|
|
<br>
|
|
After double-checking your entries for any possible errors, press the
|
|
"Commit" button. Your [% terms.bug %] report will now be in
|
|
the [% terms.Bugzilla %] database.<br>
|
|
</p>
|
|
</blockquote>
|
|
<hr>
|
|
|
|
<h3><a name="more">More Information on Writing Good [% terms.Bugs %]</a></h3>
|
|
|
|
<blockquote>
|
|
<p><b><a name="tips"></a> 1. General Tips for a Useful [% terms.Bug %]
|
|
Report</b></p>
|
|
|
|
<blockquote>
|
|
<p><b>Use an explicit structure, so your [% terms.bug %] reports are easy
|
|
to skim.</b> [% terms.Bug %] report users often need immediate access to
|
|
specific sections of your [% terms.bug %]. Follow the structure
|
|
recommended above.</p>
|
|
|
|
<p><b>Avoid cuteness if it costs clarity.</b> Nobody will be laughing
|
|
at your funny [% terms.bug %] title at 3:00 AM when they can't remember how
|
|
to find your [% terms.bug %].</p>
|
|
|
|
<p><b>One [% terms.bug %] per report.</b> Completely different people
|
|
typically fix, verify, and prioritize different [% terms.bugs %]. If you
|
|
mix a handful of [% terms.bugs %] into a single report, the right people
|
|
probably won't discover your [% terms.bugs %] in a timely fashion, if at
|
|
all. Certain [% terms.bugs %] are also more important than others. It's
|
|
impossible to prioritize [% terms.abug %] report when
|
|
it contains four different issues, all of differing importance.</p>
|
|
|
|
<p><b>No [% terms.bug %] is too trivial to report.</b> Unless you're
|
|
reading the source code, you can't see actual software [% terms.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 [% terms.Bug %]
|
|
Summaries</b></p>
|
|
|
|
<blockquote>
|
|
<p><b>You want to make a good first impression on the [% terms.bug %]
|
|
recipient.</b> Just like a New York Times headline guides readers
|
|
towards a relevant article from dozens of choices, will
|
|
your [% terms.bug %] summary suggest that your [% terms.bug %] report is
|
|
worth reading from dozens or hundreds of choices?</p>
|
|
|
|
<p>Conversely, a vague [% terms.bug %] summary like <tt>install
|
|
problem</tt> forces anyone reviewing installation [% terms.bugs %] to waste
|
|
time opening up your [% terms.bug %] to determine whether it matters.</p>
|
|
|
|
<p><b>Your [% terms.bug %] will often be searched by its summary.</b> Just
|
|
as you'd find web pages with Google by searching with keywords, so will other
|
|
people locate your [% terms.bugs %]. Descriptive [% terms.bug %] summaries are
|
|
naturally keyword-rich and easier to find.</p>
|
|
|
|
<p>For example, you'll find [% terms.abug %] 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 [% terms.abug %] titled "<tt>Dragging icons doesn't paste</tt>".</p>
|
|
|
|
<p>Ask yourself, "Would someone understand my [% terms.bug %] from just
|
|
this summary?" If so, you've succeeded.</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 [% terms.bug %] titles:</b></p>
|
|
|
|
<ol>
|
|
<li>"Save button disabled after failed post attempt" -
|
|
Explains the problem and context.</li>
|
|
|
|
<li>"Enter & Escape have no effect in 'Upload Photos' dialog" -
|
|
Also explains the problem and context.</li>
|
|
</ol>
|
|
</blockquote>
|
|
</blockquote>
|
|
|
|
[% INCLUDE global/footer.html.tmpl %]
|