path: root/template/en/default/pages/bug-writing.html.tmpl

[%# 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 &amp; 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 &amp; Escape have no effect in 'Upload Photos' dialog" -
      Also explains the problem and context.</li>
    </ol>
  </blockquote>
</blockquote>

[% INCLUDE global/footer.html.tmpl %]