diff options
| -rw-r--r-- | template/en/default/pages/bug-writing.html.tmpl | 273 |
1 files changed, 54 insertions, 219 deletions
diff --git a/template/en/default/pages/bug-writing.html.tmpl b/template/en/default/pages/bug-writing.html.tmpl index 6df5d5fef..6c6f27dbe 100644 --- a/template/en/default/pages/bug-writing.html.tmpl +++ b/template/en/default/pages/bug-writing.html.tmpl @@ -30,157 +30,79 @@ [% 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> + <p>Effective [% terms.bug %] reports are the most likely to be fixed. + These guidelines explain how to write such reports. -<blockquote> - <p>Useful [% terms.bug %] reports get [% terms.bugs %] fixed. - A useful [% terms.bug %] report has two qualities:</p> +<h3>Principles</h3> <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> + <li>Be precise</li> + <li>Be clear - explain it so others can reproduce the [% terms.bug %]</li> + <li>One [% terms.bug %] per report</li> + <li>No [% terms.bug %] is too trivial to report - + small [% terms.bugs %] may hide big [% terms.bugs %]</li> + <li>Clearly separate fact from speculation</li> </ul> -</blockquote> - -<h3><a name="before">Before You Start...</a></h3> +<h3>Preliminaries</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> + <li>Reproduce your [% terms.bug %] using a recent build of the + software, to see whether it has already been fixed. + </li> + + <li><a href="query.cgi?format=specific">Search</a> + [% terms.Bugzilla %], to see whether your [% terms.bug %] has + already been reported.</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>Reporting a New [% terms.Bug %]</h3> -<h3><a name="reporting">Reporting a New [% terms.Bug %]</a></h3> +<p>If you have reproduced the [% terms.bug %] in a recent build and +no-one else appears to have reported it, then:</p> <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> - + <li>Choose + "<a href="enter_bug.cgi">Enter a new [% terms.bug %]</a>"</li> + <li>Select the product in which you've found the [% terms.bug %]</li> + <li>Fill out the form. Here is some help understanding it:</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 + <p><b>Component:</b> In which sub-part of the software 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> + This field is required. + Click the word "Component" to see a description of each + component. If none seems appropriate, look for a "General" 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> + If you know the [% terms.bug %] happens on more than one type of + operating system, choose "All". + If your OS isn't listed, choose Other.</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> + report</b>. It should explain the problem, not your suggested solution.<br> + <ul> + <li>Good: "<tt>Cancelling a File Copy dialog crashes + File Manager</tt>"</li> + <li>Bad: "<tt>Software crashes</tt>"</li> + <li>Bad: "<tt>Browser should work with my web site</tt>"</li> + </ul> + + <b>Description:</b> + The details of your problem report, including:</p> <blockquote> - <p><b>Overview Description:</b> More detailed restatement of + <p><b>Overview:</b> More detailed restatement of summary.</p> <blockquote> <pre> -Drag-selecting any page crashes Mac builds in NSGetFactory +Drag-selecting any page crashes Mac builds in the NSGetFactory function. </pre> </blockquote> @@ -189,7 +111,8 @@ 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 @@ -232,116 +155,28 @@ Build 2006-08-10 on Mac OS 10.4.3 <blockquote> <pre> -- Doesn't Occur On Build 2006-08-10 on Windows XP Home (Service Pack 2) +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> + <p><b>Additional Information:</b> Any other useful information. + <br><br>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> - + <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 + <p>Double-check your report for errors and omissions, then press "Commit". + 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 & Escape have no effect in 'Upload Photos' dialog" - - Also explains the problem and context.</li> - </ol> - </blockquote> -</blockquote> [% INCLUDE global/footer.html.tmpl %] |