diff options
| author | terry%mozilla.org <> | 2000-03-08 02:59:38 +0100 |
|---|---|---|
| committer | terry%mozilla.org <> | 2000-03-08 02:59:38 +0100 |
| commit | 77f66018f328fe5321fa95d76515a187231ad1f0 (patch) | |
| tree | f61480d46cd47f5c5272b71d85d74ff21fdceca8 /bugwritinghelp.html | |
| parent | 7f9697e92f49678189365c0a70349a55bf8d83c1 (diff) | |
| download | bugzilla-77f66018f328fe5321fa95d76515a187231ad1f0.tar.gz bugzilla-77f66018f328fe5321fa95d76515a187231ad1f0.tar.xz | |
Contribution by Eli Goldberg <eli@prometheus-music.com> -- generic
bug-writing guidelines.
Diffstat (limited to 'bugwritinghelp.html')
| -rw-r--r-- | bugwritinghelp.html | 281 |
1 files changed, 281 insertions, 0 deletions
diff --git a/bugwritinghelp.html b/bugwritinghelp.html new file mode 100644 index 000000000..11bb7f3f5 --- /dev/null +++ b/bugwritinghelp.html @@ -0,0 +1,281 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> +<HTML> + +<HEAD> + <META NAME="GENERATOR" Content="Symantec Visual Page 1.0"> + <META HTTP-EQUIV="Content-Type" CONTENT="text/html;CHARSET=iso-8859-1"> + <TITLE>Bug Writing Guidelines</TITLE> +</HEAD> + +<BODY TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000"> + +<H1 ALIGN="CENTER">bug writing guidelines</H1> +<P ALIGN="CENTER"><FONT SIZE="2"><B>(Please send feedback/update requests to </B></FONT><A +HREF="mailto:eli@prometheus-music.com"><FONT SIZE="2"><B>Eli Goldberg</B></FONT></A><FONT +SIZE="2"><B>)</B></FONT></P> +<P><FONT SIZE="4"><B><BR> +Why You Should Read This</B></FONT> + + +<BLOCKQUOTE> + <P>Simply put, the more effectively you report a bug, the more likely an engineer + will actually fix it. <BR> + <A HREF="http://bugzilla.mozilla.org"><BR> + </A>These bug writing guidelines are an attempt at a general tutorial on writing + effective bug reports for novice bug writers; not every sentence may precisely apply + to your software project. + +</BLOCKQUOTE> + +<P><FONT SIZE="4"><B><BR> +How to Write a Useful Bug Report</B></FONT> + + +<BLOCKQUOTE> + <P>Useful bug reports are ones that get bugs fixed. A useful bug report normally + has two qualities: + + <OL> + <LI><B>Reproducible.</B> If an engineer can't see it or conclusively prove that it + exists, the engineer will probably stamp it "WORKSFORME" or "INVALID", + and move on to the next bug. Every detail you can provide helps. <BR> + <BR> + + <LI><B>Specific.</B> The quicker the engineer can isolate the issue to a specific + problem, the more likely it'll be expediently fixed.<B> </B>(If a programmer or tester + has to decypher a bug, they spend more time cursing the submitter than fixing or + testing the problem.) + </OL> + + <P>Let's say the application you're testing is a web browser. You crash at foo.com, + and want to write up a bug report: + + <BLOCKQUOTE> + <P><B>BAD:</B> "My browser crashed. I think I was on foo.com. My computer uses + Windows. I think that this is a really bad problem and you should fix it now. By + the way, your icons really suck. Nobody will use your software if you keep those + ugly icons. Oh, and my grandmother's home page doesn't look right, either, it's all + messed up. Good luck."<BR> + <BR> + <B>GOOD: </B>"I crashed each time when I went to foo.com, using the 10.28.99 + build on a Win NT 4.0 (Service Pack 5) system. I also rebooted into Linux, and reproduced + this problem using the 10.28.99 Linux build.<BR> + <BR> + 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:<BR> + <BR> + <FONT SIZE="2"><TT><IMG SRC="http://foo.com/images/topics/topicfoos.gif" + width=34 height=44 border=0 alt="News"></TT>"</FONT> + + </BLOCKQUOTE> + +</BLOCKQUOTE> + +<P><FONT SIZE="4"><B><BR> +<BR> +How to Enter your Useful Bug Report into Bugzilla</B>:</FONT> + + +<BLOCKQUOTE> + <P>Before you enter your bug, use the Bugzilla Query Page to determine whether the + defect you've discovered is a known bug, and has already been reported. (If your + bug is the 37th duplicate of a known issue, you're more likely to annoy the engineer. + Annoyed engineers fix fewer bugs.)<BR> + <BR> + Next, be sure that you've reproduced your bug using a recent build. (Engineers tend + to be most interested in problems afflicting the code base that they're actively + working on, rather than those in a code base that's hundreds of bug fixes obsolete.)<BR> + <BR> + If you've discovered a new bug using a current build, report it in Bugzilla: + +</BLOCKQUOTE> + + +<OL> + <OL> + <LI>From your Bugzilla main page, choose "Enter a new bug". + <LI>Select the product that you've found a bug in. + <LI>Enter your E-mail address, Password, and press the "Login" button. + (If you don't yet have a password, leave the password text box empty, and press the + "E-mail me a password" button instead. You'll receive an E-mail message + with your password shortly.) + </OL> + <P>Now, fill out the form. Here's what it all means: +</OL> + + + +<BLOCKQUOTE> + <P><B>Where did you find the bug?</B> + + <BLOCKQUOTE> + <P><B>Product: In which product did you find the bug?</B><BR> + You just filled this out on the last page.</P> + <P><B>Version: In which product version did you find the bug?</B><BR> + If applicable.</P> + <P><B>Component: In which component does the bug exist?</B><BR> + Bugzilla requires that you select a component to enter a bug. (If they all look meaningless, + click on the Component link, which links to descriptions of each component, to help + you make the best choice.)</P> + <P><B>Platform: On which hardware platform did you find this bug?</B><FONT SIZE="2"><B> + </B>(e.g. Macintosh, SGI, Sun, PC.) </FONT><BR> + If you know the bug happens on all hardware platforms, choose 'All'. Otherwise, select + the platform that you found the bug on, or "Other" if your platform isn't + listed.</P> + <P><B>OS: On which Operating System (OS) did you find this bug?</B> <FONT SIZE="2">(e.g. + Linux, Windows NT, Mac OS 8.5.)</FONT><BR> + If you know the bug happens on all OSs, choose 'All'. Otherwise, select the OS that + you found the bug on, or "Other" if your OS isn't listed.</P> + + </BLOCKQUOTE> + <P><B><BR> + How important is the bug?</B> + + <BLOCKQUOTE> + <P><B>Severity: How damaging is the bug?</B><BR> + This item defaults to 'normal'. (To determine the most appropriate severity for a + particular bug, click on the Severity link for a full explanation of each choice, + from Critical to Enhancement.) + + </BLOCKQUOTE> + <P><B><BR> + Who will be following up on the bug?</B> + + <BLOCKQUOTE> + <P><B>Assigned To: Which engineer should be responsible for fixing this bug?</B><BR> + Bugzilla will automatically assign the bug to a default engineer upon submitting + a bug report; the text box exists to allow you to manually assign it to a different + engineer. (To see the list of default engineers for each component, click on the + Component link.)</P> + <P><B>Cc: Who else should receive e-mail updates on changes to this bug? </B><BR> + List the full e-mail addresses of other individuals who should receive an e-mail + update upon every change to the bug report. You can enter as many e-mail addresses + as you'd like; e-mail addresses must be separated by commas, with no spaces between + the addresses. + + </BLOCKQUOTE> + <P><B><BR> + What else can you tell the engineer about the bug?</B></P> + + <BLOCKQUOTE> + <P><B>URL: On what URL did you discover this bug?</B><BR> + If you encountered the bug on a particular URL, please provide it (or, them) here. + If you've isolated the bug to a specific HTML snippet, please also provide a URL + for that, too.</P> + + <P><B>Summary:</B> <B>How would you describe the bug, in approximately 60 or fewer + characters?</B><BR> + A good summary should <U>quickly and uniquely identify a bug report</U>. Otherwise, + developers cannot meaningfully query by bug summary, and will often fail to pay attention + to your bug report when reviewing a 10 page bug list.<BR> + <BR> + A summary of "PCMCIA install fails on Tosh Tecra 780DVD w/ 3c589C" is a + useful title. "Software fails" or "install problem" would be + examples of a bad title.</P> + + <P><BR> + <B>Description: What else can you tell the engineer about this bug? </B><BR> + Please provide as detailed of a problem diagnosis in this field as possible. <BR> + <BR> + Where applicable, using the following bug report template will help ensure that all + relevant information comes through: + + <BLOCKQUOTE> + <P><B>Overview Description:</B> More detailed expansion of summary. + + <BLOCKQUOTE> + <PRE><FONT SIZE="2">Drag-selecting any page crashes Mac builds in NSGetFactory</FONT></PRE> + + </BLOCKQUOTE> + <P><B>Steps to Reproduce: </B>The minimal set of steps necessary to trigger the bug. + Include any special setup steps. + + <BLOCKQUOTE> + <PRE><FONT SIZE="2">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.)</FONT></PRE> + + </BLOCKQUOTE> + <P><B>Actual Results:</B> What the application did after performing the above steps. + + <BLOCKQUOTE> + <PRE><FONT SIZE="2">The application crashed. Stack crawl appended below from MacsBug.</FONT></PRE> + + </BLOCKQUOTE> + <P><B>Expected Results:</B> What the application should have done, were the bug not + present. + + <BLOCKQUOTE> + <PRE><FONT SIZE="2">The window should scroll downwards. Scrolled content should +be selected. (Or, at least, the application should not crash.)</FONT></PRE> + + </BLOCKQUOTE> + <P><B>Build Date & Platform:</B> Date and platform of the build that you first + encountered the bug in. + + <BLOCKQUOTE> + <PRE><FONT SIZE="2">11/2/99 build on Mac OS (Checked Viewer & Apprunner)</FONT></PRE> + + </BLOCKQUOTE> + <P><B>Additional Builds and Platforms:</B> Whether or not the bug takes place on + other platforms or browsers. + + <BLOCKQUOTE> + <PRE><FONT SIZE="2"> - Occurs On + Seamonkey (11/2/99 build on Windows NT 4.0) + + - Doesn't Occur On + Seamonkey (11/4/99 build on Red Hat Linux; feature not supported) + Internet Explorer 5.0 (RTM build on Windows NT 4.0) + Netscape Communicator 4.5 (RTM build on Mac OS)</FONT> +</PRE> + + </BLOCKQUOTE> + <P><B>Additional Information:</B> Any other debugging information. For crashing bugs: + + <UL> + <LI><B>Win32:</B> 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) + <LI><B>Mac OS:</B> if you're running MacsBug, please provide the results of a <B><TT>how</TT></B> + and an <B><TT>sc</TT></B>. + <LI><B>Unix: </B>please provide a minimized stack trace, which can be generated by + typing <B><TT>gdb apprunner core</TT></B> into a shell prompt. + </UL> + + + <BLOCKQUOTE> + <P> + <PRE><FONT SIZE="2">*** 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</FONT></PRE> + + </BLOCKQUOTE> + + </BLOCKQUOTE> + + </BLOCKQUOTE> + <P>You're done! <BR> + <BR> + After double-checking your entries for any possible errors, press the "Commit" + button, and your bug report will now be in the Bugzilla database.<BR> + <I><BR> + <BR> + </I><FONT SIZE="2">(Thanks to Claudius Gayle, Peter Mock, Chris Pratt, Tom Schutter, + and Chris Yeh for contributing to this document. Constructive </FONT><A HREF="mailto:eli@prometheus-music.com"><FONT + SIZE="2">suggestions</FONT></A><FONT SIZE="2"> welcome.)</FONT> + </BLOCKQUOTE> + + +</BODY> + +</HTML> |