From b4a70343d5c428144ab3fb215a4b962879eb3c53 Mon Sep 17 00:00:00 2001 From: "lpsolit%gmail.com" <> Date: Tue, 26 Sep 2006 18:07:21 +0000 Subject: Bug 352165: Improve the "Bug Writing Guidelines" - Patch by eli@prometheus-music.com r=gerv, r=timeless a=justdave --- template/en/default/pages/bug-writing.html.tmpl | 293 ++++++++++-------------- 1 file changed, 125 insertions(+), 168 deletions(-) (limited to 'template') 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 # Gervase Markham + # 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" %] -

Why You Should Read This

+[% PROCESS "global/field-descs.none.tmpl" %] + +[% INCLUDE global/header.html.tmpl title = "$terms.Bug Writing Guidelines" %] + +

Contents

+ + +

Why You Should Read This

Simply put, the more effectively you report [% terms.abug %], the more - likely an - engineer will actually fix it.

- -

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.

+ likely an engineer will actually fix it. This tutorial teaches novice and + intermediate [% terms.bug %] reporters how to write effective + [% terms.bug %] reports.

-

How to Write a Useful [% terms.Bug %] Report

+

What Makes [% terms.aBug %] Report Useful?

-

Useful [% terms.bug %] reports are ones that get [% terms.bugs %] fixed. - A useful [% terms.bug %] report normally has two qualities:

- -
    -
  1. Reproducible. 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.
    +

    Useful [% terms.bug %] reports get [% terms.bugs %] fixed. + A useful [% terms.bug %] report has two qualities:

    + +
      +
    • It's Reproducible. 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 %]".

      • -
    • Specific. 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.)
      -
      - [ Tell Me More ]
      • -
- -

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:

+
  • It's Specific. 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.)
    +
    • + -
    -

    BAD: "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."

    - -

    GOOD: "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.

    - -

    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:

    - -

    <IMG SRC="http://www.foo.com/images/topics/topicfoos.gif" - width="34" height="44" border="0" alt="News">

    -
    -

    How to Enter your Useful [% terms.Bug %] Report - into [% terms.Bugzilla %]:

    +

    Before You Start...

    -
    -

    Before you enter your [% terms.bug %], use [% terms.Bugzilla %]'s - search page 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 %].)

    - -

    Next, be sure to reproduce your [% terms.bug %] using a recent build. +

      +
    1. Before you enter your [% terms.bug %], use [% terms.Bugzilla %]'s + search page to determine whether + your [% terms.bug %] is known.
      2. + +
    2. 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.

      + on which they're actively working. The [% terms.bug %] you're + reporting may already be fixed.
      3. +
    -

    If you've discovered a new [% terms.bug %] using a current build, report - it in [% terms.Bugzilla %]:

    +
    +Can't find your [% terms.bug %] in [% terms.Bugzilla %]? And you can reproduce +it in a recent build? Let's report it. +
    -
      -
    1. From your [% terms.Bugzilla %] main page, choose - "Enter a new [% terms.bug %]".
      2. +

      Reporting a New [% terms.Bug %]

      -
    2. Select the product that you've found a [% terms.bug %] in.
      3. +
        +
      1. From [% terms.Bugzilla %]'s main page, choose + "Enter a new [% terms.bug %]".
        2. -
      2. 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.)
        3. -
      +
    3. Select the product in which you've found [% terms.abug %].
      4. + +
    4. Log into [% terms.Bugzilla %].
      5. + +
    5. Fill out the form. Here's what it all means:
      6. + +
    -

    Now, fill out the form. Here's what it all means:

    Where did you find the [% terms.bug %]?

    -

    Product: In which product did you find the [% terms.bug %]?
    +

    Product: In which product did you find it?
    You just specified this on the last page, so you can't edit it here.

    -

    Version: In which product version did you find - the [% terms.bug %]?
    +

    Version: In which product version did you find + it?
    (If applicable)

    -

    Component: In which component does the [% terms.bug %] - exist?
    +

    Component: In which component does it + exist?
    [% 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.)

    - -

    OS: On which Operating System (OS) did you find - this [% terms.bug %]? - (e.g. Linux, Windows 2000, Mac OS 9.)
    - 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.

    + [% terms.abug %]. (Click the Component link to see a description of each + component.)

    + +

    OS: On which operating system (OS) did you find + it? + (e.g. Linux, Windows XP, Mac OS X.)
    + If the [% terms.bug %] happens on all operating systems, choose "All". + Otherwise, select the OS, or "Other" if your OS isn't listed.

    How important is the [% terms.bug %]?

    -

    Severity: How damaging is the [% terms.bug %]?
    - 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.
    +

    Severity: How damaging is it?
    + The default is 'normal' severity. (Click on the Severity link to see + a description of each severity rating.

    Who will be following up on the [% terms.bug %]?

    -

    Assigned To: Which engineer should be responsible for fixing - this [% terms.bug %]?
    - [% terms.Bugzilla %] will automatically assign the [% terms.bug %] to a +

    Assigned To: Which engineer should be responsible for fixing + it?
    + [% 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.)

    - -

    Cc: Who else should receive e-mail updates on changes to this - [% terms.bug %]?
    - 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.

    + 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.)

    + +

    Cc: Who else should receive e-mail updates on changes to this + [% terms.bug %]?
    + 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.

    What else can you tell the engineer about the [% terms.bug %]?

    -

    Summary: How would you describe the [% terms.bug %], in - approximately 60 or fewer characters?
    +

    Summary: How would you describe the [% terms.bug %], in + approximately 60 or fewer characters?
    A good summary should quickly and uniquely identify [% terms.abug %] - report. 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.
    + report. If an engineer can't identify your + [% terms.bug %] by its summary, it may be ignored when skimming through a + 10-page list.

    - A useful summary might be "PCMCIA install fails on Tosh Tecra - 780DVD w/ 3c589C". "Software fails" or "install - problem" would be examples of a bad summary.
    -
    - [ Tell Me More ]
    + A useful summary is "Cancelling a File Copy dialog crashes Nautilus". + Examples of bad summaries would be "Software crashes" or "copy problem".

    Description:
    - Please provide a detailed problem report in this field. Your - [% terms.bug %]'s recipients will most likely expect the following - information:

    + Provide a detailed problem report. [% terms.aBug %]'s recipients usually + expect the following information:

    -

    Overview Description: More detailed expansion of +

    Overview Description: More detailed restatement of summary.

    @@ -213,13 +189,12 @@ Drag-selecting any page crashes Mac builds in NSGetFactory 
    -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.)
    @@ -228,7 +203,7 @@ browser's content region.) 
    -The application crashed. Stack crawl appended below from MacsBug.
+The application crashed.
    @@ -243,11 +218,11 @@ The window should scroll downwards. Scrolled content should be selected.

    Build Date & Platform: Date and platform of the build - that you first encountered the [% terms.bug %] in.

    + in which you first encountered the [% terms.bug %].

    -Build 2002-03-15 on Mac OS 9.0
+Build 2006-08-10 on Mac OS 10.4.3
    @@ -257,13 +232,7 @@ Build 2002-03-15 on Mac OS 9.0 
    -- 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)
    @@ -271,38 +240,27 @@ Netscape Communicator 4.5 (shipping build on Mac OS 9.0) For crashing [% terms.bugs %]:

      -
    • Win32: 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)
      • +
    • Windows: Note the type of the crash, and the module that the + application crashed in (e.g. access violation in apprunner.exe).
      • + +
    • Mac OS X: 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!
      • -
    • Mac OS: if you're running MacsBug, please provide the - results of a how and an sc:
    -
    -
    -*** 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
-
    -
    -

    You're done!

    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.

    -

    More Information on Writing Good [% terms.Bugs %]

    +

    More Information on Writing Good [% terms.Bugs %]

    1. General Tips for a Useful [% terms.Bug %] @@ -311,8 +269,8 @@ PowerPC unmapped memory exception at 0B512BD0 NSGetFactory+055F0

    Use an explicit structure, so your [% terms.bug %] reports are easy to skim. [% 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.

    + specific sections of your [% terms.bug %]. Follow the structure + recommended above.

    Avoid cuteness if it costs clarity. 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

    One [% terms.bug %] per report. 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.

    @@ -350,18 +308,17 @@ PowerPC unmapped memory exception at 0B512BD0 NSGetFactory+055F0 time opening up your [% terms.bug %] to determine whether it matters.

    Your [% terms.bug %] will often be searched by its summary. 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.

    + 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.

    -

    For example, you'll find a [% terms.bug %] titled "Dragging icons +

    For example, you'll find [% terms.abug %] titled "Dragging icons from List View to gnome-terminal doesn't paste path" if you search on "List", "terminal", or "path". Those search keywords wouldn't have - found a [% terms.bug %] titled "Dragging icons doesn't paste".

    + found [% terms.abug %] titled "Dragging icons doesn't paste".

    Ask yourself, "Would someone understand my [% terms.bug %] from just - this summary?" If so, you've written a fine summary.

    + this summary?" If so, you've succeeded.

    Don't write titles like these:

    @@ -378,11 +335,11 @@ PowerPC unmapped memory exception at 0B512BD0 NSGetFactory+055F0

    Good [% terms.bug %] titles:

      -
    1. "1.0 upgrade installation fails if Mozilla M18 package present" - - Explains problem and the context.
      2. +
    2. "Save button disabled after failed post attempt" - + Explains the problem and context.
      3. -
    3. "RPM 4 installer crashes if launched on Red Hat 6.2 (RPM 3) - system" - Explains what happens, and the context.
      4. +
    4. "Enter & Escape have no effect in 'Upload Photos' dialog" - + Also explains the problem and context.
    -- cgit v1.2.3-24-g4f1b