зеркало из https://github.com/mozilla/pjs.git
Bug 378590 - rewrite and reduce the length of the bug-writing guidelines. Patch by gerv; r=lpsolit,mkanat, a=mkanat
This commit is contained in:
gerv%gerv.net
Родитель
97a05d7c20
Коммит
8cf91dc033
|
|
@ -30,157 +30,79 @@
|
||||||
|
|
||||||
[% INCLUDE global/header.html.tmpl title = "$terms.Bug Writing Guidelines" %]
|
[% INCLUDE global/header.html.tmpl title = "$terms.Bug Writing Guidelines" %]
|
||||||
|
|
||||||
<h3>Contents</h3>
|
<p>Effective [% terms.bug %] reports are the most likely to be fixed.
|
||||||
<ul>
|
These guidelines explain how to write such reports.
|
||||||
<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>
|
<h3>Principles</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>
|
<ul>
|
||||||
<li><b>It's Reproducible.</b> Engineers usually prefer to fix [% terms.bugs %]
|
<li>Be precise</li>
|
||||||
they can actually see. If an engineer can't reproduce the [% terms.bug %],
|
<li>Be clear - explain it so others can reproduce the [% terms.bug %]</li>
|
||||||
it'll probably be stamped "[% get_resolution("WORKSFORME") FILTER html %]" or
|
<li>One [% terms.bug %] per report</li>
|
||||||
"[% get_resolution("INVALID") FILTER html %]".<br>
|
<li>No [% terms.bug %] is too trivial to report -
|
||||||
<br>
|
small [% terms.bugs %] may hide big [% terms.bugs %]</li>
|
||||||
</li>
|
<li>Clearly separate fact from speculation</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>
|
</ul>
|
||||||
|
|
||||||
</blockquote>
|
<h3>Preliminaries</h3>
|
||||||
|
|
||||||
<h3><a name="before">Before You Start...</a></h3>
|
|
||||||
|
|
||||||
<ol>
|
<ol>
|
||||||
<li>Before you enter your [% terms.bug %], use [% terms.Bugzilla %]'s
|
<li>Reproduce your [% terms.bug %] using a recent build of the
|
||||||
<a href="query.cgi?format=specific">search page</a> to determine whether
|
software, to see whether it has already been fixed.
|
||||||
your [% terms.bug %] is known.</li>
|
</li>
|
||||||
|
|
||||||
<li>Reproduce your [% terms.bug %] using a recent build.
|
<li><a href="query.cgi?format=specific">Search</a>
|
||||||
Engineers tend to be most interested in problems affecting the code base
|
[% terms.Bugzilla %], to see whether your [% terms.bug %] has
|
||||||
on which they're actively working. The [% terms.bug %] you're
|
already been reported.</li>
|
||||||
reporting may already be fixed.</li>
|
|
||||||
</ol>
|
</ol>
|
||||||
|
|
||||||
<blockquote>
|
<h3>Reporting a New [% terms.Bug %]</h3>
|
||||||
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>
|
<p>If you have reproduced the [% terms.bug %] in a recent build and
|
||||||
|
no-one else appears to have reported it, then:</p>
|
||||||
|
|
||||||
<ol>
|
<ol>
|
||||||
<li>From [% terms.Bugzilla %]'s main page, choose
|
<li>Choose
|
||||||
"<a href="enter_bug.cgi">Enter a new [% terms.bug %]</a>".</li>
|
"<a href="enter_bug.cgi">Enter a new [% terms.bug %]</a>"</li>
|
||||||
|
<li>Select the product in which you've found the [% terms.bug %]</li>
|
||||||
<li>Select the product in which you've found [% terms.abug %].</li>
|
<li>Fill out the form. Here is some help understanding it:</li>
|
||||||
|
|
||||||
<li>Log into [% terms.Bugzilla %].</li>
|
|
||||||
|
|
||||||
<li>Fill out the form. Here's what it all means:</li>
|
|
||||||
|
|
||||||
</ol>
|
</ol>
|
||||||
|
|
||||||
|
|
||||||
<p><b>Where did you find the [% terms.bug %]?</b></p>
|
|
||||||
|
|
||||||
<blockquote>
|
<blockquote>
|
||||||
<p><b>Product:</b> In which product did you find it?<br>
|
<p><b>Component:</b> In which sub-part of the software does it
|
||||||
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>
|
exist?<br>
|
||||||
[% terms.Bugzilla %] requires that you select a component to enter
|
This field is required.
|
||||||
[% terms.abug %]. (Click the Component link to see a description of each
|
Click the word "Component" to see a description of each
|
||||||
component.)</p>
|
component. If none seems appropriate, look for a "General" component.</p>
|
||||||
|
|
||||||
<p><b>OS:</b> On which operating system (OS) did you find
|
<p><b>OS:</b> On which operating system (OS) did you find
|
||||||
it?
|
it?
|
||||||
(e.g. Linux, Windows XP, Mac OS X.)<br>
|
(e.g. Linux, Windows XP, Mac OS X.)<br>
|
||||||
If the [% terms.bug %] happens on all operating systems, choose "All".
|
If you know the [% terms.bug %] happens on more than one type of
|
||||||
Otherwise, select the OS, or "Other" if your OS isn't listed.</p>
|
operating system, choose "All".
|
||||||
</blockquote>
|
If your OS isn't listed, choose Other.</p>
|
||||||
|
|
||||||
<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
|
<p><b>Summary:</b> How would you describe the [% terms.bug %], in
|
||||||
approximately 60 or fewer characters?<br>
|
approximately 60 or fewer characters?<br>
|
||||||
A good summary should <b>quickly and uniquely identify [% terms.abug %]
|
A good summary should <b>quickly and uniquely identify [% terms.abug %]
|
||||||
report</b>. If an engineer can't identify your
|
report</b>. It should explain the problem, not your suggested solution.<br>
|
||||||
[% terms.bug %] by its summary, it may be ignored when skimming through a
|
<ul>
|
||||||
10-page list.<br>
|
<li>Good: "<tt>Cancelling a File Copy dialog crashes
|
||||||
<br>
|
File Manager</tt>"</li>
|
||||||
A useful summary is "<tt>Cancelling a File Copy dialog crashes Nautilus</tt>".
|
<li>Bad: "<tt>Software crashes</tt>"</li>
|
||||||
Examples of bad summaries would be "<tt>Software crashes</tt>" or "<tt>copy problem</tt>".<br>
|
<li>Bad: "<tt>Browser should work with my web site</tt>"</li>
|
||||||
<br>
|
</ul>
|
||||||
<b>Description:</b><br>
|
|
||||||
Provide a detailed problem report. [% terms.aBug %]'s recipients usually
|
<b>Description:</b>
|
||||||
expect the following information:</p>
|
The details of your problem report, including:</p>
|
||||||
|
|
||||||
<blockquote>
|
<blockquote>
|
||||||
<p><b>Overview Description:</b> More detailed restatement of
|
<p><b>Overview:</b> More detailed restatement of
|
||||||
summary.</p>
|
summary.</p>
|
||||||
|
|
||||||
<blockquote>
|
<blockquote>
|
||||||
<pre>
|
<pre>
|
||||||
Drag-selecting any page crashes Mac builds in NSGetFactory
|
Drag-selecting any page crashes Mac builds in the NSGetFactory function.
|
||||||
</pre>
|
</pre>
|
||||||
</blockquote>
|
</blockquote>
|
||||||
|
|
||||||
|
|
@ -189,7 +111,8 @@ Drag-selecting any page crashes Mac builds in NSGetFactory
|
||||||
|
|
||||||
<blockquote>
|
<blockquote>
|
||||||
<pre>
|
<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
|
2) Drag-select the page. (Specifically, while holding down
|
||||||
the mouse button, drag the mouse pointer downwards from any
|
the mouse button, drag the mouse pointer downwards from any
|
||||||
|
|
@ -232,116 +155,28 @@ Build 2006-08-10 on Mac OS 10.4.3
|
||||||
|
|
||||||
<blockquote>
|
<blockquote>
|
||||||
<pre>
|
<pre>
|
||||||
- Doesn't Occur On Build 2006-08-10 on Windows XP Home (Service Pack 2)
|
Doesn't Occur On Build 2006-08-10 on Windows XP Home (Service Pack 2)
|
||||||
</pre>
|
</pre>
|
||||||
</blockquote>
|
</blockquote>
|
||||||
|
|
||||||
<p><b>Additional Information:</b> Any other debugging information.
|
<p><b>Additional Information:</b> Any other useful information.
|
||||||
For crashing [% terms.bugs %]:</p>
|
<br><br>For crashing [% terms.bugs %]:</p>
|
||||||
|
|
||||||
<ul>
|
<ul>
|
||||||
<li><b>Windows:</b> Note the type of the crash, and the module that the
|
<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>
|
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.
|
<li><b>Mac OS X:</b> Attach the "Crash Reporter" log that appears
|
||||||
Only include the section directly below the crashing thread, usually titled
|
upon crash.
|
||||||
"Thread 0 Crashed". Please do not paste the entire log!</li>
|
Only include the section directly below the crashing thread, usually
|
||||||
|
titled "Thread 0 Crashed". Please do not paste the entire log!</li>
|
||||||
</ul>
|
</ul>
|
||||||
|
|
||||||
</blockquote>
|
</blockquote>
|
||||||
|
|
||||||
<p>You're done!<br>
|
<p>Double-check your report for errors and omissions, then press "Commit".
|
||||||
<br>
|
Your [% terms.bug %] report will now be in
|
||||||
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>
|
the [% terms.Bugzilla %] database.<br>
|
||||||
</p>
|
</p>
|
||||||
</blockquote>
|
</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 %]
|
[% INCLUDE global/footer.html.tmpl %]
|
||||||
|
|
|
||||||
Загрузка…
Ссылка в новой задаче