From 77f66018f328fe5321fa95d76515a187231ad1f0 Mon Sep 17 00:00:00 2001
From: "terry%mozilla.org" <>
Date: Wed, 8 Mar 2000 01:59:38 +0000
Subject: [PATCH] Contribution by Eli Goldberg <eli@prometheus-music.com> --
generic bug-writing guidelines.
---
bugwritinghelp.html | 281 ++++++++++++++++++++++++++++++++++++++++++++
defparams.pl | 2 +-
2 files changed, 282 insertions(+), 1 deletion(-)
create mode 100644 bugwritinghelp.html
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>
diff --git a/defparams.pl b/defparams.pl
index 14fecf10c..c65de7664 100644
--- a/defparams.pl
+++ b/defparams.pl
@@ -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.",
--
2.24.1