mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-10-30 13:45:27 +00:00
282 lines
11 KiB
HTML
282 lines
11 KiB
HTML
<!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>
|