Contribution by Eli Goldberg <eli@prometheus-music.com> -- generic
bug-writing guidelines.
This commit is contained in:
terry%mozilla.org
Родитель
ba7a7b144d
Коммит
3d1c7c6a0f
|
|
@ -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>
|
||||
|
|
@ -444,7 +444,7 @@ DefParam("webdotbase",
|
|||
DefParam("entryheaderhtml",
|
||||
"This is a special header for the bug entry page. The text will be printed after the page header, before the bug entry form. It is meant to be a place to put pointers to intructions on how to enter bugs.",
|
||||
"l",
|
||||
'');
|
||||
'<A HREF="bugwritinghelp.html">Bug writing guidelines</A>');
|
||||
|
||||
DefParam("expectbigqueries",
|
||||
"If this is on, then we will tell mysql to <tt>set option SQL_BIG_TABLES=1</tt> before doing queries on bugs. This will be a little slower, but one will not get the error <tt>The table ### is full</tt> for big queries that require a big temporary table.",
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче