[%# 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 # Gervase Markham # 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" %]

Contents

Why You Should Read This

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.

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

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 FILTER html %]" or "[% resolution_descs.INVALID FILTER html %]".

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

Before You Start...

  1. Before you enter your [% terms.bug %], use [% terms.Bugzilla %]'s search page to determine whether your [% terms.bug %] is known.
  2. 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.
Can't find your [% terms.bug %] in [% terms.Bugzilla %]? And you can reproduce it in a recent build? Let's report it.

Reporting a New [% terms.Bug %]

  1. From [% terms.Bugzilla %]'s main page, choose "Enter a new [% terms.bug %]".
  2. Select the product in which you've found [% terms.abug %].
  3. Log into [% terms.Bugzilla %].
  4. Fill out the form. Here's what it all means:

Where 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 it?
(If applicable)

Component: In which component does it exist?
[% terms.Bugzilla %] requires that you select a component to enter [% 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 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 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 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?
A good summary should quickly and uniquely identify [% terms.abug %] 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 is "Cancelling a File Copy dialog crashes Nautilus". Examples of bad summaries would be "Software crashes" or "copy problem".

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

Overview Description: More detailed restatement of summary.

Drag-selecting any page crashes Mac builds in NSGetFactory

Steps to Reproduce: Minimized, easy-to-follow steps that will trigger the [% terms.bug %]. Include any special setup steps.

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

Actual Results: What the application did after performing the above steps.

The application crashed.

Expected Results: What the application should have done, were the [% terms.bug %] not present.

The window should scroll downwards. Scrolled content should be selected. 
(Or, at least, the application should not crash.)

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

Build 2006-08-10 on Mac OS 10.4.3

Additional Builds and Platforms: Whether or not the [% terms.bug %] takes place on other platforms (or browsers, if applicable).

- Doesn't Occur On Build 2006-08-10 on Windows XP Home (Service Pack 2)

Additional Information: Any other debugging information. For crashing [% terms.bugs %]:

  • 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!

You're done!

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.

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

1. General Tips for a Useful [% terms.Bug %] Report

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 %]. 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 to find your [% terms.bug %].

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

No [% terms.bug %] is too trivial to report. 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.

2. How and Why to Write Good [% terms.Bug %] Summaries

You want to make a good first impression on the [% terms.bug %] recipient. 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?

Conversely, a vague [% terms.bug %] summary like install problem forces anyone reviewing installation [% terms.bugs %] to waste 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 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 [% 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 [% terms.abug %] titled "Dragging icons doesn't paste".

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

Don't write titles like these:

  1. "Can't install" - Why can't you install? What happens when you try to install?
  2. "Severe Performance Problems" - ...and they occur when you do what?
  3. "back button does not work" - Ever? At all?

Good [% terms.bug %] titles:

  1. "Save button disabled after failed post attempt" - Explains the problem and context.
  2. "Enter & Escape have no effect in 'Upload Photos' dialog" - Also explains the problem and context.
[% INCLUDE global/footer.html.tmpl %]