aboutsummaryrefslogtreecommitdiffstats
path: root/bugwritinghelp.html
blob: 11bb7f3f5cb9e052cc4a8eece8dabbb19dd16191 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
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 &quot;WORKSFORME&quot; or &quot;INVALID&quot;,
	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> &quot;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.&quot;<BR>
		<BR>
		<B>GOOD: </B>&quot;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 &quot;border=0&quot; attribute:<BR>
		<BR>
		<FONT SIZE="2"><TT>&lt;IMG SRC=&quot;http://foo.com/images/topics/topicfoos.gif&quot;
		width=34 height=44 border=0 alt=&quot;News&quot;&gt;</TT>&quot;</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 &quot;Enter a new bug&quot;.
		<LI>Select the product that you've found a bug in.
		<LI>Enter your E-mail address, Password, and press the &quot;Login&quot; button.
		(If you don't yet have a password, leave the password text box empty, and press the
		&quot;E-mail me a password&quot; 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:&#160;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 &quot;Other&quot; 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 &quot;Other&quot; 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 &quot;PCMCIA install fails on Tosh Tecra 780DVD w/ 3c589C&quot; is a
		useful title. &quot;Software fails&quot; or &quot;install problem&quot; 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 &amp; 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 &amp; 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 &quot;Commit&quot;
	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>