Bug 352165: Improve the "Bug Writing Guidelines" - Patch by eli@prometheus-music.com r=gerv, r=timeless a=justdave

1 files changed, 125 insertions, 168 deletions

diff --git a/template/en/default/pages/bug-writing.html.tmpl b/template/en/default/pages/bug-writing.html.tmpl
index 0317ae6a1..8cfa76b0f 100644
--- a/template/en/default/pages/bug-writing.html.tmpl
+++ b/template/en/default/pages/bug-writing.html.tmpl
@@ -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>
-
-  <ol>
-    <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>
+
+  <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 "[% 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>&lt;IMG SRC="http://www.foo.com/images/topics/topicfoos.gif"
-    width="34" height="44" border="0" alt="News"&gt;</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 &amp; 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 2002-03-15 on Mac OS 9.0
+Build 2006-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 your [% terms.bug %] report will now be in 
+  "Commit" button. Your [% 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.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 a [% terms.bug %] titled "<tt>Dragging icons doesn't paste</tt>".</p>
+    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 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 present" -
-      Explains problem and the context.</li>
+      <li>"Save button disabled after failed post attempt" -
+      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 &amp; Escape have no effect in 'Upload Photos' dialog" -
+      Also explains the problem and context.</li>
     </ol>
   </blockquote>
 </blockquote>