Skip to content
Projects
Groups
Snippets
Help
This project
Loading...
Sign in / Register
Toggle navigation
bugzilla
Project
Project
Details
Activity
Cycle Analytics
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Charts
Issues
0
Issues
0
List
Board
Labels
Milestones
Merge Requests
0
Merge Requests
0
CI / CD
CI / CD
Pipelines
Jobs
Schedules
Charts
Wiki
Wiki
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Charts
Create a new issue
Jobs
Commits
Issue Boards
Open sidebar
etersoft
bugzilla
Commits
b4a70343
Commit
b4a70343
authored
Sep 26, 2006
by
lpsolit%gmail.com
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
Bug 352165: Improve the "Bug Writing Guidelines" - Patch by…
Bug 352165: Improve the "Bug Writing Guidelines" - Patch by eli@prometheus-music.com r=gerv, r=timeless a=justdave
parent
b93a222f
Hide whitespace changes
Inline
Side-by-side
Showing
1 changed file
with
125 additions
and
168 deletions
+125
-168
bug-writing.html.tmpl
template/en/default/pages/bug-writing.html.tmpl
+125
-168
No files found.
template/en/default/pages/bug-writing.html.tmpl
View file @
b4a70343
...
...
@@ -18,188 +18,164 @@
#
# 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/variables.none.tmpl %]
[% INCLUDE global/header.html.tmpl title = "$terms.Bug Writing Guidelines" %]
<h3>Why You Should Read This</h3>
[% 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.</p>
<p>These guidelines are a general tutorial to teach novice and
intermediate [% terms.bug %] reporters how to compose effective
[% terms.bug %] reports. Not
every sentence may precisely apply to your software project.</p>
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>
How to Write a Useful [% terms.Bug %] Report
</h3>
<h3>
<a name="useful">What Makes [% terms.aBug %] Report Useful?</a>
</h3>
<blockquote>
<p>Useful [% terms.bug %] reports
are ones that
get [% terms.bugs %] fixed.
A useful [% terms.bug %] report
normally
has two qualities:</p>
<
o
l>
<li><b>
Reproducible.</b> If an engineer can't see the [% terms.bug
%]
herself to prove that it exists, she'll probably stamp your [% terms.bug %]
report "WORKSFORME" or "INVALID" and move on to the next [% terms.bug %].
Every detail you can provide helps
.<br>
<p>Useful [% terms.bug %] reports get [% terms.bugs %] fixed.
A useful [% terms.bug %] report has two qualities:</p>
<
u
l>
<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 "[% resolution_descs.WORKSFORME %]" or
"[% resolution_descs.INVALID %]"
.<br>
<br>
</li>
<li><b>Specific.</b> The quicker the engineer can isolate the
[% terms.bug %] to a specific area, the more likely she'll expediently
fix it. (If a programmer or tester has to decipher [% terms.abug %],
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 [% terms.bug %] report:</p>
<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>
<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 [% terms.Bug %] Report
into [% terms.Bugzilla %]:</h3>
<h3><a name="before">Before You Start...</a></h3>
<blockquote>
<p>Before you enter your [% terms.bug %], use [% terms.Bugzilla %]'s
<a href="query.cgi">search page</a> to determine whether the defect
you've discovered is a known, already-reported [% terms.bug %]. If
your [% terms.bug %] is the 37th duplicate of a known issue,
you're more likely to annoy the engineer. (Annoyed engineers fix fewer
[% terms.bugs %].)</p>
<p>Next, be sure to reproduce your [% terms.bug %] using a recent build.
<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
that they're actively working on. After all, the [% terms.bug %] you're
reporting may already be fixed.</p>
on which they're actively working. The [% terms.bug %] you're
reporting may already be fixed.</li>
</ol>
<p>If you've discovered a new [% terms.bug %] using a current build, report
it in [% terms.Bugzilla %]:</p>
<blockquote>
Can't find your [% terms.bug %] in [% terms.Bugzilla %]? And you can reproduce
it in a recent build? Let's report it.
</blockquote>
<ol>
<li>From your [% terms.Bugzilla %] main page, choose
"<a href="enter_bug.cgi">Enter a new [% terms.bug %]</a>".</li>
<h3><a name="reporting">Reporting a New [% terms.Bug %]</a></h3>
<li>Select the product that you've found a [% terms.bug %] in.</li>
<ol>
<li>From [% terms.Bugzilla %]'s main page, choose
"<a href="enter_bug.cgi">Enter a new [% terms.bug %]</a>".</li>
<li>Enter your e-mail address, password, and press the "Log in" button.
(If you don't yet have a password, enter your email address below and
press the "Submit Request" button instead. You'll quickly receive
an e-mail message with your password.)</li>
</ol>
<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>Now, fill out the form. Here's what it all means:</p>
<p><b>Where did you find the [% terms.bug %]?</b></p>
<blockquote>
<p><b>Product:
In which product did you find the [% terms.bug %]?</b>
<br>
<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: In which product version did you find
the [% terms.bug %]?</b>
<br>
<p><b>Version:
</b>
In which product version did you find
it?
<br>
(If applicable)</p>
<p><b>Component:
In which component does the [% terms.bug %]
exist?<
/b><
br>
<p><b>Component:
</b> In which component does it
exist?<br>
[% terms.Bugzilla %] requires that you select a component to enter
a [% terms.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 [% terms.bug %]?</b>
(e.g. Linux, Windows 2000, Mac OS 9.)<br>
If you know the [% terms.bug %] happens on all OSs, choose 'All'.
Otherwise, select the OS that you found the [% terms.bug %] on, or
"Other" if your OS isn't listed.</p>
[% 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: How damaging is the [% terms.bug %]?</b><br>
This item defaults to 'normal'. If you're not sure what severity your
[% terms.bug %] deserves, click on the Severity link. You'll see a
description of each severity rating.<br>
<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: Which engineer should be responsible for fixing
this [% terms.bug %]?</b>
<br>
[% terms.Bugzilla %]
will automatically assign
the [% terms.bug %] to a
<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 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
[% terms.bug %]?</b><br>
List the full e-mail addresses of other individuals who should receive
an e-mail update upon every change to the [% terms.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 [% terms.Bugzilla %] accounts.</p>
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>
<b>
How would you describe the [% terms.bug %], in
approximately 60 or fewer characters?<
/b><
br>
<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>. Otherwise, an engineer cannot meaningfully identify your
[% terms.bug %] by its summary, and will often fail to pay attention to
your [% terms.bug %] report when skimming through a 10
page [% terms.bug %] list.<br>
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 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>
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>
Please provide a detailed problem report in this field. Your
[% terms.bug %]'s recipients will most likely expect the following
information:</p>
Provide a detailed problem report. [% terms.aBug %]'s recipients usually
expect the following information:</p>
<blockquote>
<p><b>Overview Description:</b> More detailed
expansion
of
<p><b>Overview Description:</b> More detailed
restatement
of
summary.</p>
<blockquote>
...
...
@@ -213,13 +189,12 @@ Drag-selecting any page crashes Mac builds in NSGetFactory
<blockquote>
<pre>
1) View any web page. (I used the default sample page,
resource:/res/samples/test0.html)
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.)
browser's content region.)
</pre>
</blockquote>
...
...
@@ -228,7 +203,7 @@ browser's content region.)
<blockquote>
<pre>
The application crashed.
Stack crawl appended below from MacsBug.
The application crashed.
</pre>
</blockquote>
...
...
@@ -243,11 +218,11 @@ The window should scroll downwards. Scrolled content should be selected.
</blockquote>
<p><b>Build Date & Platform:</b> Date and platform of the build
that you first encountered the [% terms.bug %] in
.</p>
in which you first encountered the [% terms.bug %]
.</p>
<blockquote>
<pre>
Build 200
2-03-15 on Mac OS 9.0
Build 200
6-08-10 on Mac OS 10.4.3
</pre>
</blockquote>
...
...
@@ -257,13 +232,7 @@ Build 2002-03-15 on Mac OS 9.0
<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)
- Doesn't Occur On Build 2006-08-10 on Windows XP Home (Service Pack 2)
</pre>
</blockquote>
...
...
@@ -271,38 +240,27 @@ Netscape Communicator 4.5 (shipping build on Mac OS 9.0)
For crashing [% terms.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>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>
<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 y
our [% terms.bug %] report will now be in
"Commit" button
. Y
our [% terms.bug %] report will now be in
the [% terms.Bugzilla %] database.<br>
</p>
</blockquote>
<hr>
<h3>
More Information on Writing Good [% terms.Bugs %]
</h3>
<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 %]
...
...
@@ -311,8 +269,8 @@ PowerPC unmapped memory exception at 0B512BD0 NSGetFactory+055F0
<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 %].
If your [% terms.Bugzilla %]
installation supports the [% terms.Bugzilla %] Helper, use it
.</p>
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
...
...
@@ -321,7 +279,7 @@ PowerPC unmapped memory exception at 0B512BD0 NSGetFactory+055F0
<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,
or
at
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>
...
...
@@ -350,18 +308,17 @@ PowerPC unmapped memory exception at 0B512BD0 NSGetFactory+055F0
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 by keywords through
intuition, so will other people locate your [% terms.bugs %].
Descriptive [% terms.bug %] summaries are
naturally keyword-rich, and easier to find.</p>
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
a [% terms.
bug %] titled "<tt>Dragging icons
<p>For example, you'll find
[% terms.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 [% terms.
bug %] titled "<tt>Dragging icons doesn't paste</tt>".</p>
found
[% terms.a
bug %] 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
written a fine summary
.</p>
this summary?" If so, you've
succeeded
.</p>
<p><b>Don't write titles like these:</b></p>
...
...
@@ -378,11 +335,11 @@ PowerPC unmapped memory exception at 0B512BD0 NSGetFactory+055F0
<p><b>Good [% terms.bug %] titles:</b></p>
<ol>
<li>"
1.0 upgrade installation fails if Mozilla M18 package presen
t" -
Explains
problem and the
context.</li>
<li>"
Save button disabled after failed post attemp
t" -
Explains
the problem and
context.</li>
<li>"
RPM 4 installer crashes if launched on Red Hat 6.2 (RPM 3)
system" - Explains what happens, and the
context.</li>
<li>"
Enter & Escape have no effect in 'Upload Photos' dialog" -
Also explains the problem and
context.</li>
</ol>
</blockquote>
</blockquote>
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment