From 317a88ea11f43acc511d386c65f57bbc57a93c05 Mon Sep 17 00:00:00 2001 From: "gerv%gerv.net" <> Date: Mon, 8 Mar 2004 07:27:30 +0000 Subject: Bug 170213 - make static HTML files into page.cgi pages. This does votehelp.html (-> id=voting.html), bug_status.html (-> id=fields.html) and bugwritinghelp.html (-> id=bug-writing.html). Patch by gerv; r=kiko, a=justdave. --- template/en/default/pages/bug-writing.html.tmpl | 390 ++++++++++++++++++++++++ 1 file changed, 390 insertions(+) create mode 100644 template/en/default/pages/bug-writing.html.tmpl (limited to 'template/en/default/pages/bug-writing.html.tmpl') diff --git a/template/en/default/pages/bug-writing.html.tmpl b/template/en/default/pages/bug-writing.html.tmpl new file mode 100644 index 000000000..1a228b0c4 --- /dev/null +++ b/template/en/default/pages/bug-writing.html.tmpl @@ -0,0 +1,390 @@ +[%# 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 + # 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

+ +
+

Simply put, the more effectively you report a [% terms.bug %], 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.

+
+ +

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

+ +
+

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.
    +
    +
    2. + +
  2. 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 decypher a [% terms.bug %], + they may spend more time cursing the submitter than solving the + problem.)
    +
    + [ Tell Me More ]
    3. +
+ +

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:

+ +
+

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

+ +

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

+ +
    +
  1. From your [% terms.Bugzilla %] main page, choose + "Enter a new [% terms.bug %]".
    2. + +
  2. Select the product that you've found a [% terms.bug %] in.
    3. + +
  3. Enter your e-mail address, password, and press the "Login" button. + (If you don't yet have a password, leave the password field empty, and + press the "E-mail me a password" button instead. You'll quickly receive + an e-mail message with your password.)
    4. +
+ +

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 %]?
+ 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 %]?
+ (If applicable)

+ +

Component: In which component does the [% terms.bug %] + 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.

+
+ +

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

+
+ +

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 + default engineer upon submitting a [% terms.bug %] 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.

+
+ +

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 a [% terms.bug %] + 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.
+
+ 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 ]
+
+ Description:
+ Please provide a detailed problem report in this field. Your + [% terms.bug %]'s recipients will most likely expect the following + information:

+ +
+

Overview Description: More detailed expansion 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. Stack crawl appended below from MacsBug.
+
+
+ +

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 + that you first encountered the [% terms.bug %] in.

+ +
+
+Build 2002-03-15 on Mac OS 9.0
+
+
+ +

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

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

Additional Information: Any other debugging information. + 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)
    • + +
  • 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 + 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 %]. If your [% terms.Bugzilla %] + installation supports the [% terms.Bugzilla %] Helper, use it.

+ +

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, or at + all. Certain [% terms.bugs %] are also more important than others. It's + impossible to prioritize a [% terms.bug %] 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 by keywords through + intuition, 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 + 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".

+ +

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

+ +

Don't write titles like these:

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

Good [% terms.bug %] titles:

+ +
    +
  1. "1.0 upgrade installation fails if Mozilla M18 package present" - + Explains problem and the context.
    2. + +
  2. "RPM 4 installer crashes if launched on Red Hat 6.2 (RPM 3) + system" - Explains what happens, and the context.
    3. +
+
+
+ +[% INCLUDE global/footer.html.tmpl %] -- cgit v1.2.3-24-g4f1b