/[gentoo]/xml/htdocs/doc/en/bugzilla-howto.xml

Diff of /xml/htdocs/doc/en/bugzilla-howto.xml

Parent Directory | Revision Log | View Patch Patch

Revision 1.1		Revision 1.14
1	<?xml version="1.0" encoding="UTF-8"?>	1	<?xml version="1.0" encoding="UTF-8"?>
2	<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">	2	<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.1 2005/07/07 12:02:21 fox2mike Exp $ -->	3	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.14 2009/01/26 07:34:41 nightmorph Exp $ -->
4		4
5	<guide link="/doc/en/bugzilla-howto.xml">	5	<guide link="/doc/en/bugzilla-howto.xml">
6	<title>Gentoo Bug Reporting Guide</title>	6	<title>Gentoo Bug Reporting Guide</title>
7		7
8	<author title="Author">	8	<author title="Author">
…		…
18		18
19	<!-- The content of this document is licensed under the CC-BY-SA license -->	19	<!-- The content of this document is licensed under the CC-BY-SA license -->
20	<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->	20	<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
21	<license/>	21	<license/>
22		22
23	<version>1.0</version>	23	<version>1.12</version>
24	<date>2005-07-07</date>	24	<date>2009-01-25</date>
25		25
26	<chapter>	26	<chapter>
27	<title>Introduction</title>	27	<title>Introduction</title>
28	<section>	28	<section>
29	<title>Preface</title>	29	<title>Preface</title>
30	<body>	30	<body>
31		31
32	<p>	32	<p>
33	Often one of the factors that delay a bug being fixed is how it is reported. By	33	One of the factors that delay a bug being fixed is the way it is reported. By
34	creating this guide, I hope to help improve the communication between	34	creating this guide, we hope to help improve the communication between
35	developers and users in bug resolution. Getting bugs fixed is an important, if	35	developers and users in bug resolution. Getting bugs fixed is an important, if
36	not crucial part of the quality assurance of any project and hopefully this	36	not crucial part of the quality assurance for any project and hopefully this
37	guide will help make that a success.	37	guide will help make that a success.
38	</p>	38	</p>
39		39
40	</body>	40	</body>
41	</section>	41	</section>
42	<section>	42	<section>
43	<title>Initial Finding</title>	43	<title>Bugs!!!!</title>
44	<body>	44	<body>
45		45
46	<p>	46	<p>
47	You're emerge-ing a package or working with a program, then suddenly the worst	47	You're emerge-ing a package or working with a program and suddenly the worst
48	happens -- you find a bug. Bugs come in many forms, whether it be emerge	48	happens -- you find a bug. Bugs come in many forms like emerge failures or
49	failures or segmentation faults. Whatever the cause, the fact still remains that	49	segmentation faults. Whatever the cause, the fact still remains that such a bug
50	such a bug must be fixed. Here is a few examples of such bugs.	50	must be fixed. Here is a few examples of such bugs.
51	</p>	51	</p>
52		52
53	<pre caption="A run time error">	53	<pre caption="A run time error">
54	$ <i>./bad_code `perl -e 'print Ax100'`</i>	54	$ <i>./bad_code `perl -e 'print Ax100'`</i>
55	Segmentation fault	55	Segmentation fault
…		…
84	!!! Function src_compile, Line 29, Exitcode 2	84	!!! Function src_compile, Line 29, Exitcode 2
85	!!! 'emake shared' failed	85	!!! 'emake shared' failed
86	</pre>	86	</pre>
87		87
88	<p>	88	<p>
89	These errors can be quite troublesome. However, once you find them, what do	89	These errors can be quite troublesome. However, once you find them, what do you
90	you do? The following sections will look at 2 important tools for handling	90	do? The following sections will look at two important tools for handling run
91	run time errors. After that, we'll take a look at compile errors, and how to	91	time errors. After that, we'll take a look at compile errors, and how to handle
92	handle them. Let's start out with the first tool for debugging run time	92	them. Let's start out with the first tool for debugging run time errors --
93	errors -- <c>gdb</c>	93	<c>gdb</c>.
94	</p>	94	</p>
95		95
96	</body>	96	</body>
97	</section>	97	</section>
98	</chapter>	98	</chapter>
…		…
106		106
107	<p>	107	<p>
108	GDB, or the (G)NU (D)e(B)ugger, is a program used to find run time errors that	108	GDB, or the (G)NU (D)e(B)ugger, is a program used to find run time errors that
109	normally involve memory corruption. First off, let's take a look at what	109	normally involve memory corruption. First off, let's take a look at what
110	debugging entails. One of the main things you must do in order to debug a	110	debugging entails. One of the main things you must do in order to debug a
111	program is to <c>emerge</c> the program with FEATURES="nostrip". This prevents	111	program is to <c>emerge</c> the program with <c>FEATURES="nostrip"</c>. This
112	the stripping of debug symbols. Why are programs stripped by default? The reason	112	prevents the stripping of debug symbols. Why are programs stripped by default?
113	is the same as that for having gzipped man pages -- saving space. Here's how the	113	The reason is the same as that for having gzipped man pages -- saving space.
114	size of a program varies with and without debug symbol stripping.	114	Here's how the size of a program varies with and without debug symbol stripping.
115	</p>	115	</p>
116		116
117	<pre caption="Filesize Comparison">	117	<pre caption="Filesize Comparison">
118	<comment>(debug symbols stripped)</comment>	118	<comment>(debug symbols stripped)</comment>
119	-rwxr-xr-x 1 chris users 3140 6/28 13:11 bad_code	119	-rwxr-xr-x 1 chris users 3140 6/28 13:11 bad_code
…		…
123		123
124	<p>	124	<p>
125	Just for reference, <e>bad_code</e> is the program we'll be debugging with	125	Just for reference, <e>bad_code</e> is the program we'll be debugging with
126	<c>gdb</c> later on. As you can see, the program without debugging symbols is	126	<c>gdb</c> later on. As you can see, the program without debugging symbols is
127	3140 bytes, while the program with them is 6374 bytes. That's close to double	127	3140 bytes, while the program with them is 6374 bytes. That's close to double
128	the size! Two more things can be done for debugging. The first is adding -g to	128	the size! Two more things can be done for debugging. The first is adding ggdb3
129	your CFLAGS and CXXFLAGS. This flag adds more debugging information than is	129	to your CFLAGS and CXXFLAGS. This flag adds more debugging information than is
130	generally included. We'll see what that means later on. Lastly, you can also add	130	generally included. We'll see what that means later on. This is how
131	debug to the package's USE flags. This can be done with the	131	<path>/etc/make.conf</path> <e>might</e> look with the newly added flags.
132	<path>package.use</path> file.
133	</p>	132	</p>
		133
		134	<pre caption="make.conf settings">
		135	CFLAGS="-O1 -pipe -g -ggdb"
		136	CXXFLAGS="${CFLAGS}"
		137	</pre>
		138
		139	<p>
		140	Lastly, you can also add debug to the package's USE flags. This can be done
		141	with the <path>package.use</path> file.
		142	</p>
134		143
135	<pre caption="Using package.use to add debug USE flag">	144	<pre caption="Using package.use to add debug USE flag">
136	# <i>echo "category/package debug" >> /etc/portage/package.use</i>	145	# <i>echo "category/package debug" >> /etc/portage/package.use</i>
137	</pre>	146	</pre>
138		147
…		…
142	USE flags set in <path>package.use</path>, you will need to manually modify them	151	USE flags set in <path>package.use</path>, you will need to manually modify them
143	in your favorite editor.	152	in your favorite editor.
144	</note>	153	</note>
145		154
146	<p>	155	<p>
147	Now that that's done, you will need to re-emerge your package to set the	156	Then we re-emerge the package with the modifications we've done so far as shown
148	new debug settings into place. This can be done as follows:	157	below.
149	</p>	158	</p>
150		159
151	<pre caption="Re-emergeing a package with debugging">	160	<pre caption="Re-emergeing a package with debugging">
152	# <i>FEATURES="nostrip" emerge package</i>	161	# <i>FEATURES="nostrip" emerge package</i>
153	</pre>	162	</pre>
…		…
161	<section>	170	<section>
162	<title>Running the program with GDB</title>	171	<title>Running the program with GDB</title>
163	<body>	172	<body>
164		173
165	<p>	174	<p>
166	Let's say we have a program here called "bad_code" (I know, it's sort of cheesy	175	Let's say we have a program here called "bad_code". Some person claims that the
167	but..). Some person claims he can break the code and provides an example. You go	176	program crashes and provides an example. You go ahead and test it out:
168	ahead and test it out:
169	</p>	177	</p>
170		178
171	<pre caption="Breaking The Program">	179	<pre caption="Breaking The Program">
172	$ <i>./bad_code `perl -e 'print Ax100'`</i>	180	$ <i>./bad_code `perl -e 'print Ax100'`</i>
173	Segmentation fault	181	Segmentation fault
…		…
189	Type "show copying" to see the conditions.	197	Type "show copying" to see the conditions.
190	There is absolutely no warranty for GDB. Type "show warranty" for details.	198	There is absolutely no warranty for GDB. Type "show warranty" for details.
191	This GDB was configured as "i686-pc-linux-gnu"...Using host libthread_db library "/lib/libthread_db.so.1".	199	This GDB was configured as "i686-pc-linux-gnu"...Using host libthread_db library "/lib/libthread_db.so.1".
192	</pre>	200	</pre>
193		201
		202	<note>
		203	One can also debug with core dumps. These core files contain the same
		204	information that the program would produce when run with gdb. In order to debug
		205	with a core file with bad_code, you would run <c>gdb ./bad_code core</c> where
		206	core is the name of the core file.
		207	</note>
		208
194	<p>	209	<p>
195	You should see a small terminal like setup after that which says "(gdb)" and	210	You should see a prompt that says "(gdb)" and waits for input. First, we have to
196	waits for input. First, we have to run the program. We type in <c>run</c> at the	211	run the program. We type in <c>run</c> at the command and receive a notice like:
197	command and receive a notice like:
198	</p>	212	</p>
199		213
200	<pre caption="Running the program in GDB">	214	<pre caption="Running the program in GDB">
201	(gdb) run	215	(gdb) <i>run</i>
202	Starting program: /home/chris/bad_code	216	Starting program: /home/chris/bad_code
203		217
204	Program received signal SIGSEGV, Segmentation fault.	218	Program received signal SIGSEGV, Segmentation fault.
205	0xb7ec6dc0 in strcpy () from /lib/libc.so.6	219	0xb7ec6dc0 in strcpy () from /lib/libc.so.6
206	</pre>	220	</pre>
…		…
217	up on the backtrace. To get a backtrace, at the (gdb) prompt, type in <c>bt</c>.	231	up on the backtrace. To get a backtrace, at the (gdb) prompt, type in <c>bt</c>.
218	You will get something like this:	232	You will get something like this:
219	</p>	233	</p>
220		234
221	<pre caption="Program backtrace">	235	<pre caption="Program backtrace">
222	(gdb) bt	236	(gdb) <i>bt</i>
223	#0 0xb7ec6dc0 in strcpy () from /lib/libc.so.6	237	#0 0xb7ec6dc0 in strcpy () from /lib/libc.so.6
224	#1 0x0804838c in run_it ()	238	#1 0x0804838c in run_it ()
225	#2 0x080483ba in main ()	239	#2 0x080483ba in main ()
226	</pre>	240	</pre>
227		241
228	<p>	242	<p>
229	So as we see here, first main() was run, then run_it(), and somewhere in run_it	243	You can notice the trace pattern clearly. main() is called first, followed by
230	lies the strcpy() at fault. Things such as this help developers narrow things	244	run_it(), and somewhere in run_it() lies the strcpy() at fault. Things such as
231	down. Now, there are a few exceptions to the output. First off is forgetting	245	this help developers narrow down problems. There are a few exceptions to the
232	to disable debug symbols with FEATURES="nostrip". With debug symbols stripped,	246	output. First off is forgetting to enable debug symbols with
233	output looks something like this:	247	<c>FEATURES="nostrip"</c>. With debug symbols stripped, the output looks something
		248	like this:
234	</p>	249	</p>
235		250
236	<pre caption="Program backtrace With debug symbols stripped">	251	<pre caption="Program backtrace With debug symbols stripped">
237	(gdb) bt	252	(gdb) <i>bt</i>
238	#0 0xb7e2cdc0 in strcpy () from /lib/libc.so.6	253	#0 0xb7e2cdc0 in strcpy () from /lib/libc.so.6
239	#1 0x0804838c in ?? ()	254	#1 0x0804838c in ?? ()
240	#2 0xbfd19510 in ?? ()	255	#2 0xbfd19510 in ?? ()
241	#3 0x00000000 in ?? ()	256	#3 0x00000000 in ?? ()
242	#4 0x00000000 in ?? ()	257	#4 0x00000000 in ?? ()
…		…
262	#24 0x08048201 in ?? ()	277	#24 0x08048201 in ?? ()
263	</pre>	278	</pre>
264		279
265	<p>	280	<p>
266	This backtrace contains a large number of ?? marks. This is because without	281	This backtrace contains a large number of ?? marks. This is because without
267	debug symbols, <c>gdb</c> doesn't know how the program was ran. Hence, it is	282	debug symbols, <c>gdb</c> doesn't know how the program was run. Hence, it is
268	crucial that debug symbols are <e>not</e> stripped. Now remember a while ago I	283	crucial that debug symbols are <e>not</e> stripped. Now remember a while ago we
269	told you about the -g flag. Let's see what the output looks like with that:	284	mentioned the -ggdb flag. Let's see what the output looks like with the flag
		285	enabled:
270	</p>	286	</p>
271		287
272	<pre caption="Program backtrace with -g flag">	288	<pre caption="Program backtrace with -ggdb3">
273	(gdb) bt	289	(gdb) <i>bt</i>
274	#0 0xb7e4bdc0 in strcpy () from /lib/libc.so.6	290	#0 0xb7e4bdc0 in strcpy () from /lib/libc.so.6
275	#1 0x0804838c in run_it (input=0x0) at bad_code.c:7	291	#1 0x0804838c in run_it (input=0x0) at bad_code.c:7
276	#2 0x080483ba in main (argc=1, argv=0xbfd3a434) at bad_code.c:12	292	#2 0x080483ba in main (argc=1, argv=0xbfd3a434) at bad_code.c:12
277	</pre>	293	</pre>
278		294
279	<p>	295	<p>
280	Here we see that a lot more information is available for developers. Not only is	296	Here we see that a lot more information is available for developers. Not only is
281	variable information displayed, but even the exact line numbers of the source	297	function information displayed, but even the exact line numbers of the source
282	files. This method is the most preferred if you can spare the extra space.	298	files. This method is the most preferred if you can spare the extra space.
283	Here's how much the file size varies between debug, strip, and -g programs.	299	Here's how much the file size varies between debug, strip, and -ggdb enabled
		300	programs.
284	</p>	301	</p>
285		302
286	<pre caption="Filesize differences With -g flag">	303	<pre caption="Filesize differences With -ggdb flag">
287	<comment>(debug symbols stripped)</comment>	304	<comment>(debug symbols stripped)</comment>
288	-rwxr-xr-x 1 chris users 3140 6/28 13:11 bad_code	305	-rwxr-xr-x 1 chris users 3140 6/28 13:11 bad_code
289	<comment>(debug symbols enabled)</comment>	306	<comment>(debug symbols enabled)</comment>
290	-rwxr-xr-x 1 chris users 6374 6/28 13:10 bad_code	307	-rwxr-xr-x 1 chris users 6374 6/28 13:10 bad_code
291	<comment>(-g flag enabled)</comment>	308	<comment>(-ggdb flag enabled)</comment>
292	-rwxr-xr-x 1 chris users 7366 6/28 13:11 bad_code	309	-rwxr-xr-x 1 chris users 19552 6/28 13:11 bad_code
293	</pre>	310	</pre>
294		311
295	<p>	312	<p>
296	As you can see, -g adds about a 1000 more bytes to the file size over the one	313	As you can see, -ggdb adds about <e>13178</e> more bytes to the file size over
297	with debugging symbols. However, as shown above, this increase in file size can	314	the one with debugging symbols. However, as shown above, this increase in file
298	be worth it if presenting debug information to developers. Now that we have	315	size can be worth it if presenting debug information to developers. The
299	obtained the backtrace, we can save it to a file by copying and pasting from the	316	backtrace can be saved to a file by copying and pasting from the terminal (if
300	terminal (if it's a non-x based terminal, you can use gpm. To keep this doc	317	it's a non-x based terminal, you can use gpm. To keep this doc simple, I
301	simple, I recommend you read up on the documentation for gpm to see how to copy	318	recommend you read up on the <uri link="/doc/en/gpm.xml#doc_chap4">documentation
302	and paste with it). Now that we're done with <c>gdb</c>, we can quit.	319	for gpm</uri> to see how to copy and paste with it). Now that we're done with
		320	<c>gdb</c>, we can quit.
303	</p>	321	</p>
304		322
305	<pre caption="Quitting GDB">	323	<pre caption="Quitting GDB">
306	(gdb) quit	324	(gdb) <i>quit</i>
307	The program is running. Exit anyway? (y or n) y	325	The program is running. Exit anyway? (y or n) <i>y</i>
308	$	326	$
309	</pre>	327	</pre>
310		328
311	<p>	329	<p>
312	This ends the walk-through of <c>gdb</c>. Using <c>gdb</c>, I hope that you will	330	This ends the walk-through of <c>gdb</c>. Using <c>gdb</c>, we hope that you
313	be able to use it to create better bug reports. However, there are other types	331	will be able to use it to create better bug reports. However, there are other
314	of errors that can cause a program to fail during run time. One of the other	332	types of errors that can cause a program to fail during run time. One of the
315	ways is through improper file access. We can find those using a nifty little	333	other ways is through improper file access. We can find those using a nifty
316	tool called <c>strace</c>.	334	little tool called <c>strace</c>.
317	</p>	335	</p>
318		336
319	</body>	337	</body>
320	</section>	338	</section>
321	</chapter>	339	</chapter>
…		…
325	<section>	343	<section>
326	<title>Introduction</title>	344	<title>Introduction</title>
327	<body>	345	<body>
328		346
329	<p>	347	<p>
330	Programs often use files to get configuration information, get access	348	Programs often use files to fetch configuration information, access hardware or
331	to hardware, or write logs. Often a program attempts to reach such files	349	write logs. Sometimes, a program attempts to reach such files incorrectly. A
332	incorrectly. A program called <c>strace</c> was created to help deal with	350	tool called <c>strace</c> was created to help deal with this. <c>strace</c>
333	this. <c>strace</c> traces system calls (hence the name) which include	351	traces system calls (hence the name) which include calls that use the memory and
334	calls that use the memory and files. For our example, we're going to take a	352	files. For our example, we're going to take a program foobar2. This is an
335	program foobar2. This is an updated version of foobar. However, during the	353	updated version of foobar. However, during the change over to foobar2, you
336	changeover to foobar2, you notice all your configurations are missing! In	354	notice all your configurations are missing! In foobar version 1, you had it
337	foobar version 1, you had it setup to say "foo", but now it's using the default	355	setup to say "foo", but now it's using the default "bar".
338	"bar".
339	</p>	356	</p>
340		357
341	<pre caption="Foobar2 With an invalid configuration">	358	<pre caption="Foobar2 With an invalid configuration">
342	$ <i>./foobar2</i>	359	$ <i>./foobar2</i>
343	Configuration says: bar	360	Configuration says: bar
…		…
353	<section>	370	<section>
354	<title>Using strace to track the issue</title>	371	<title>Using strace to track the issue</title>
355	<body>	372	<body>
356		373
357	<p>	374	<p>
358	Let's have <c>strace</c> log the results of the system calls. To do this, we run	375	We make <c>strace</c> log the results of the system calls. To do this, we run
359	<c>strace</c> with the -o[file] arguments. Let's use it on foobar2 like so:	376	<c>strace</c> with the -o[file] arguments. Let's use it on foobar2 as shown.
360	</p>	377	</p>
361		378
362	<pre caption="Running foobar2 through strace">	379	<pre caption="Running foobar2 through strace">
363	# <i>strace -ostrace.log ./foobar2</i>	380	# <i>strace -ostrace.log ./foobar2</i>
364	</pre>	381	</pre>
365		382
366	<p>	383	<p>
367	This creates a file called strace.log in the current directory. We check the	384	This creates a file called <path>strace.log</path> in the current directory. We
368	file, and shown below are the relevant parts from the file.	385	check the file, and shown below are the relevant parts from the file.
369	</p>	386	</p>
370		387
371	<pre caption="A Look At the strace Log">	388	<pre caption="A Look At the strace Log">
372	open(".foobar2/config", O_RDONLY) = 3	389	open(".foobar2/config", O_RDONLY) = 3
373	read(3, "bar", 3) = 3	390	read(3, "bar", 3) = 3
…		…
376	<p>	393	<p>
377	Aha! So There's the problem. Someone moved the configuration directory to	394	Aha! So There's the problem. Someone moved the configuration directory to
378	<path>.foobar2</path> instead of <path>.foobar</path>. We also see the program	395	<path>.foobar2</path> instead of <path>.foobar</path>. We also see the program
379	reading in "bar" as it should. In this case, we can recommend the ebuild	396	reading in "bar" as it should. In this case, we can recommend the ebuild
380	maintainer to put a warning about it. For now though, we can copy over the	397	maintainer to put a warning about it. For now though, we can copy over the
381	config file from .foobar and modify it to produce the correct results.	398	config file from <path>.foobar</path> and modify it to produce the correct
		399	results.
382	</p>	400	</p>
383		401
384	</body>	402	</body>
385	</section>	403	</section>
386	<section>	404	<section>
…		…
388	<body>	406	<body>
389		407
390	<p>	408	<p>
391	Now we've taken care of finding run time bugs. These bugs prove to be	409	Now we've taken care of finding run time bugs. These bugs prove to be
392	problematic when you try and run your programs. However, run time errors are	410	problematic when you try and run your programs. However, run time errors are
393	the least of your concern if your program won't compile at all. Let's take a	411	the least of your concerns if your program won't compile at all. Let's take a
394	look at how to address <c>emerge</c> compile errors.	412	look at how to address <c>emerge</c> compile errors.
395	</p>	413	</p>
396		414
397	</body>	415	</body>
398	</section>	416	</section>
…		…
404	<title>Introduction</title>	422	<title>Introduction</title>
405	<body>	423	<body>
406		424
407	<p>	425	<p>
408	<c>emerge</c> errors, such as the one displayed earlier, can be a major cause	426	<c>emerge</c> errors, such as the one displayed earlier, can be a major cause
409	of frustration for users. Reporting them is considered crucial for helping	427	of frustration for users. Reporting them is considered crucial for maintaining
410	maintain the health of Gentoo. Let's take a look at a sample ebuild, foobar2,	428	the health of Gentoo. Let's take a look at a sample ebuild, foobar2, which
411	which contains some build errors.	429	contains some build errors.
412	</p>	430	</p>
413		431
414	</body>	432	</body>
415	</section>	433	</section>
416	<section id="emerge_error">	434	<section id="emerge_error">
…		…
419		437
420	<p>	438	<p>
421	Let's take a look at this very simple <c>emerge</c> error:	439	Let's take a look at this very simple <c>emerge</c> error:
422	</p>	440	</p>
423		441
424	<pre caption="emerge Error">	442	<pre caption="emerge Error (long lines are manually wrapped to fit the window)">
425	gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2-7.o foobar2-7.c
426	gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2-8.o foobar2-8.c
427	gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2-9.o foobar2-9.c
428	gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2.o foobar2.c	443	gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod \
		444	-c -o foobar2-7.o foobar2-7.c
		445	gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod \
		446	-c -o foobar2-8.o foobar2-8.c
		447	gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod \
		448	-c -o foobar2-9.o foobar2-9.c
		449	gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod \
		450	-c -o foobar2.o foobar2.c
429	foobar2.c:1:17: ogg.h: No such file or directory	451	foobar2.c:1:17: ogg.h: No such file or directory
430	make: *** [foobar2.o] Error 1	452	make: *** [foobar2.o] Error 1
431		453
432	!!! ERROR: sys-apps/foobar2-1.0 failed.	454	!!! ERROR: sys-apps/foobar2-1.0 failed.
433	!!! Function src_compile, Line 19, Exitcode 2	455	!!! Function src_compile, Line 19, Exitcode 2
434	!!! Make failed!	456	!!! Make failed!
435	!!! If you need support, post the topmost build error, NOT this status message	457	!!! If you need support, post the topmost build error, NOT this status message
436	</pre>	458	</pre>
437		459
438	<p>	460	<p>
439	The compile is going smoothly, then it stops and presents an error message. This	461	The program is compiling smoothly when it suddenly stops and presents an error
440	particular error can be split into 3 different sections, The compile, the build	462	message. This particular error can be split into 3 different sections, The
441	error, and the emerge error message as shown below.	463	compile messages, the build error, and the emerge error message as shown below.
442	</p>	464	</p>
443		465
444	<pre caption="Parts of the error">	466	<pre caption="Parts of the error (long lines are manually wrapped to fit the window)">
445	<comment>(Compile Error)</comment>	467	<comment>(Compilation Messages)</comment>
446	gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2-7.o foobar2-7.c
447	gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2-8.o foobar2-8.c
448	gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2-9.o foobar2-9.c
449	gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2.o foobar2.c	468	gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod \
		469	-c -o foobar2-7.o foobar2-7.c
		470	gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod \
		471	-c -o foobar2-8.o foobar2-8.c
		472	gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod \
		473	-c -o foobar2-9.o foobar2-9.c
		474	gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod \
		475	-c -o foobar2.o foobar2.c
450		476
451	<comment>(Build Error)</comment>	477	<comment>(Build Error)</comment>
452	foobar2.c:1:17: ogg.h: No such file or directory	478	foobar2.c:1:17: ogg.h: No such file or directory
453	make: *** [foobar2.o] Error 1	479	make: *** [foobar2.o] Error 1
454		480
455	<comment>(Emerge Error)</comment>	481	<comment>(emerge Error)</comment>
456	!!! ERROR: sys-apps/foobar2-1.0 failed.	482	!!! ERROR: sys-apps/foobar2-1.0 failed.
457	!!! Function src_compile, Line 19, Exitcode 2	483	!!! Function src_compile, Line 19, Exitcode 2
458	!!! Make failed!	484	!!! Make failed!
459	!!! If you need support, post the topmost build error, NOT this status message	485	!!! If you need support, post the topmost build error, NOT this status message
460	</pre>	486	</pre>
461		487
462	<p>	488	<p>
463	The compile is what leads up to the error. Most often, it's good to at least	489	The compilation messages are what lead up to the error. Most often, it's good to
464	include 10 lines of compile information so that the developer knows where the	490	at least include 10 lines of compile information so that the developer knows
465	compile is at. Make errors are the actual error, and the information the	491	where the compilation was at when the error occurred.
466	developer needs. When you see "make: ***", this is often where the error has	492	</p>
467	occurred. Normally, you can copy and paste 10 lines above it and the developer	493
468	will be able to address the issue. However, this may not always work and we'll	494	<p>
469	take a look at an alternative shortly. The emerge error is what <c>emerge</c>	495	Make errors are the actual error and the information the developer needs. When
470	can address from the make error. Often people make the mistake of posting the	496	you see "make: ***", this is often where the error has occurred. Normally, you
		497	can copy and paste 10 lines above it and the developer will be able to address
		498	the issue. However, this may not always work and we'll take a look at an
		499	alternative shortly.
		500	</p>
		501
		502	<p>
		503	The emerge error is what <c>emerge</c> throws out as an error. Sometimes, this
		504	might also contain some important information. Often people make the mistake of
471	emerge error and that's all. This is useless by itself, but with make error and	505	posting the emerge error and that's all. This is useless by itself, but with
472	compile information, a developer can get what application and what version of	506	make error and compile information, a developer can get what application and
473	the package is failing. As a side note, make is commonly used as the build	507	what version of the package is failing. As a side note, make is commonly used as
474	process for programs (<b>but not always</b>). If you can't find a "make: ***"	508	the build process for programs (<b>but not always</b>). If you can't find a
475	error anywhere, then simply copy and paste 20 lines before the emerge error.	509	"make: ***" error anywhere, then simply copy and paste 20 lines before the
476	This should take care of most all build system error messages. Now let's say the	510	emerge error. This should take care of most all build system error messages. Now
477	errors seem to be quite large. 10 lines won't be enough to catch everything.	511	let's say the errors seem to be quite large. 10 lines won't be enough to catch
478	That's where PORT_LOGDIR comes into play.	512	everything. That's where PORT_LOGDIR comes into play.
479	</p>	513	</p>
480		514
481	</body>	515	</body>
482	</section>	516	</section>
483	<section>	517	<section>
484	<title>emerge and PORT_LOGDIR</title>	518	<title>emerge and PORT_LOGDIR</title>
485	<body>	519	<body>
486		520
487	<p>	521	<p>
488	PORT_LOGDIR is a portage variable that sets up a log directory for separate	522	PORT_LOGDIR is a portage variable that sets up a log directory for separate
489	emerge logs. Let's take a look and see what that entails. First, run your emerge	523	emerge logs. Let's take a look and see what that entails. First, run your
490	with PORT_LOGDIR set to your favorite log location. Let's say we have a	524	emerge with PORT_LOGDIR set to your favorite log location. Let's say we have a
491	location /var/log/portage. We'll use that for our log directory:	525	location <path>/var/log/portage</path>. We'll use that for our log directory:
492	</p>	526	</p>
493		527
494	<note>	528	<note>
495	In the default setup, /var/log/portage does not exist, and you will most likely	529	In the default setup, <path>/var/log/portage</path> does not exist, and you will
496	have to create it. If you do not, portage will fail to write the logs.	530	most likely have to create it. If you do not, portage will fail to write the
		531	logs.
497	</note>	532	</note>
498		533
499	<pre caption="emerge-ing With PORT_LOGDIR">	534	<pre caption="emerge-ing With PORT_LOGDIR">
500	# <i>PORT_LOGDIR=/var/log/portage emerge foobar2</i>	535	# <i>PORT_LOGDIR=/var/log/portage emerge cate-gory/foobar2</i>
501	</pre>	536	</pre>
502		537
503	<p>	538	<p>
504	Now the emerge fails again. However, this time we have a log we can work with,	539	Now the emerge fails again. However, this time we have a log we can work with,
505	and attach to the bug later on. Let's take a quick look at our log directory.	540	and attach to the bug later on. Let's take a quick look at our log directory.
…		…
508	<pre caption="PORT_LOGDIR Contents">	543	<pre caption="PORT_LOGDIR Contents">
509	# <i>ls -la /var/log/portage</i>	544	# <i>ls -la /var/log/portage</i>
510	total 16	545	total 16
511	drwxrws--- 2 root root 4096 Jun 30 10:08 .	546	drwxrws--- 2 root root 4096 Jun 30 10:08 .
512	drwxr-xr-x 15 root root 4096 Jun 30 10:08 ..	547	drwxr-xr-x 15 root root 4096 Jun 30 10:08 ..
513	-rw-r--r-- 1 root root 7390 Jun 30 10:09 2115-foobar2-1.0.log	548	-rw-r--r-- 1 root root 7390 Jun 30 10:09 cate-gory:foobar2-1.0:20090110-213217.log
514	</pre>	549	</pre>
515		550
516	<p>	551	<p>
517	The log files have the format [counter]-[package name]-[version].log. Counter	552	The log files have the format [category]:[package name]-[version]:[date].log. A
518	is a special variable that is meant to state this package as the n-th package
519	you've emerged. This prevents duplicate logs from appearing. A quick look at
520	the log file will show the entire emerge process. This can be attached later	553	quick look at the log file will show the entire emerge process. This can be
521	on as we'll see in the bug reporting section. Now that we've safely obtained	554	attached later on as we'll see in the bug reporting section. Now that we've
522	our information needed to report the bug we can continue to do so. However,	555	safely obtained our information needed to report the bug we can continue to do
523	before we get started on that, we need to make sure no one else has reported	556	so. However, before we get started on that, we need to make sure no one else
524	the issue. Let's take a look at searching for bugs.	557	has reported the issue. Let's take a look at searching for bugs.
525	</p>	558	</p>
526		559
527	</body>	560	</body>
528	</section>	561	</section>
529	</chapter>	562	</chapter>
…		…
536		569
537	<p>	570	<p>
538	<uri link="http://www.bugzilla.org">Bugzilla</uri> is what we at Gentoo use to	571	<uri link="http://www.bugzilla.org">Bugzilla</uri> is what we at Gentoo use to
539	handle bugs. Gentoo's Bugzilla is reachable by HTTPS and HTTP. HTTPS is	572	handle bugs. Gentoo's Bugzilla is reachable by HTTPS and HTTP. HTTPS is
540	available for those on insecure networks or simply paranoid :). For the sake of	573	available for those on insecure networks or simply paranoid :). For the sake of
541	consistency, I will be using the HTTPS version in the examples to follow. Head	574	consistency, we will be using the HTTPS version in the examples to follow. Head
542	over to <uri link="https://bugs.gentoo.org">Gentoo Bugs</uri> to see how it	575	over to <uri link="https://bugs.gentoo.org">Gentoo Bugs</uri> to see how it
543	looks.	576	looks.
544	</p>	577	</p>
545		578
546	<p>	579	<p>
547	One of the most frustrating thing for developers and bug-wranglers is finding	580	One of the most frustrating things for developers and bug-wranglers is finding
548	duplicate bug reports. This causes them valuable time they could be using to	581	duplicate bug reports. These cost them valuable time that they could otherwise
549	find new and more important bugs. Often, this can be prevented by a few simple	582	use to work on more important bugs. Often, this can be prevented by a few simple
550	search methods. So we're going to see how to search for bugs and find out if	583	search methods. So we're going to see how to search for bugs and find out if
551	you have one that's similar. For this example, we're going to use the xclass	584	you have one that's similar. For this example, we're going to use the xclass
552	emerge error that was used earlier:	585	emerge error that was used earlier.
553	</p>	586	</p>
554		587
555	<pre caption="xclass emerge error">	588	<pre caption="xclass emerge error">
556	/usr/lib/gcc-lib/i686-pc-linux-gnu/3.3.2/include/g++-v3/backward/backward_warning.h:32:2:	589	/usr/lib/gcc-lib/i686-pc-linux-gnu/3.3.2/include/g++-v3/backward/backward_warning.h:32:2:
557	warning: #warning This file includes at least one deprecated or antiquated	590	warning: #warning This file includes at least one deprecated or antiquated
…		…
582	!!! 'emake shared' failed	615	!!! 'emake shared' failed
583	</pre>	616	</pre>
584		617
585	<p>	618	<p>
586	So to begin searching, we head over to the <uri	619	So to begin searching, we head over to the <uri
587	link="http://bugs.gentoo.org/">Bugzilla Homepage</uri>.	620	link="https://bugs.gentoo.org/">Bugzilla Homepage</uri>.
588	</p>	621	</p>
589		622
590	<figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/>	623	<figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/>
591		624
592	<p>	625	<p>
593	In order to begin our search, we'll click on "Query Existing bug reports". The	626	We'll click on "Query Existing bug reports". The reason why we choose this
594	reason why we choose this versus the basic bug search is because the basic bug	627	over the basic bug search is because the basic bug search tends to give vague
595	search tends to give vague results and often hinders users from looking	628	results and often hinders users from looking through the results and finding the
596	through the results and finding the duplicate bug. Once we click on the query	629	duplicate bug. Once we click on the query screen, we reach the next page:
597	screen, we reach the next page:
598	</p>	630	</p>
599		631
600	<figure link="/images/docs/bugzie-search.png" caption="Bugzilla Search Page"/>	632	<figure link="/images/docs/bugzie-search.png" caption="Bugzilla Search Page"/>
601		633
602	<note>	634	<note>
603	If you've used the Advanced Search before, you'll most likely see that screen	635	If you've used the Advanced Search before, you'll most likely see that screen
604	instead.	636	instead.
605	</note>	637	</note>
606		638
607	<p>	639	<p>
608	Proceed on clicking the "Advanced Search" link to bring up the Advanced	640	Proceed by clicking on the "Advanced Search" link to bring up the Advanced
609	Search page:	641	Search page.
610	</p>	642	</p>
611		643
612	<figure link="/images/docs/bugzie-adv-search.png" caption="Advanced Search Page"/>	644	<figure link="/images/docs/bugzie-adv-search.png" caption="Advanced Search Page"/>
613		645
614	<p>	646	<p>
615	This is how the Advanced Search Page looks like. While it may seem overwhelming	647	This is how the Advanced Search Page looks like. While it may seem overwhelming
616	at first, we're going to look at a few simple areas to narrow down the rather	648	at first, we're going to look at a few simple areas to narrow down the rather
617	vague searches bugzilla returns.	649	vague searches bugzilla returns.
618	</p>	650	</p>
619		651
620	<figure link="/images/docs/bugzie-content.png" caption="Content"/>	652	<figure link="/images/docs/bugzie-content.png" caption="Content"/>
621		653
622	<p>	654	<p>
623	The first field is the summary of the bug. Here we're simply going to put the	655	The first field is the summary of the bug. Here we're simply going to put the
624	name of the package that's crashing. If you still don't get results, try	656	name of the package that's crashing. If bugzie doesn't return results, try
625	removing the package name, just in case someone didn't put that in the summary	657	removing the package name, just in case someone didn't put that in the summary
626	(highly unlikely, but I've seen my fair share of strange bug reports).	658	(highly unlikely, but we've seen a fair share of strange bug reports).
627	</p>	659	</p>
628		660
629	<p>	661	<p>
630	Product, Component, and Version should all be set to the default. This	662	Product, Component, and Version should all be set to the default. This
631	prevents us from being too specific and missing all the bugs.	663	prevents us from being too specific and missing all the bugs.
632	</p>	664	</p>
633		665
634	<p>	666	<p>
635	Comment is the important part. Use comment to list what appears to be a	667	Comment is the important part. Use the comment field to list what appears to be
636	specific instance of the error. Basically, don't use anything like the	668	a specific instance of the error. Basically, don't use anything like the
637	beginning of the build error, find a line that's before it stating a true	669	beginning of the build error, find a line that's before it stating a true
638	error. Also, you'll want to filter out any punctuation to prevent bugzilla	670	error. Also, you'll want to filter out any punctuation to prevent bugzilla
639	from interpreting the results the comment the wrong way. Example from the xclass	671	from interpreting the results the comment the wrong way. Example from the xclass
640	emerge error:	672	emerge error:
641	</p>	673	</p>
…		…
651	other xclass compile failure candidates.	683	other xclass compile failure candidates.
652	</p>	684	</p>
653		685
654	<p>	686	<p>
655	URI, Whiteboard, and Keywords can all be left alone. What we've entered so far	687	URI, Whiteboard, and Keywords can all be left alone. What we've entered so far
656	should be enough to find our bug. Let's see what we have filled out:	688	should be enough to find our bug. Let's take a look at what we have filled out.
657	</p>	689	</p>
658		690
659	<figure link="/images/docs/bugzie-comp-search.png" caption="Completed Search Form"/>	691	<figure link="/images/docs/bugzie-comp-search.png" caption="Completed Search Form"/>
660		692
661	<p>	693	<p>
662	Now we click on the Search button and here come the results:	694	Now we click on the Search button and here come the results...
663	</p>	695	</p>
664		696
665	<figure link="/images/docs/bugzie-search-result.png" caption="Search Results"/>	697	<figure link="/images/docs/bugzie-search-result.png" caption="Search Results"/>
666		698
667	<p>	699	<p>
668	Only 2 bugs! That's a lot easier to deal with. We click on the first one to	700	Only 2 bugs! That's a lot easier to deal with. We click on the first one to
669	check, and sure enough it's the one we're looking for:	701	check, and sure enough it's the one we're looking for.
670	</p>	702	</p>
671		703
672	<figure link="/images/docs/bugzie-located.png" caption="Bug Located"/>	704	<figure link="/images/docs/bugzie-located.png" caption="Bug Located"/>
673		705
674	<p>	706	<p>
675	Not only is it the one we want, but it has also been resolved. By checking the	707	Not only is it the one we want, but it has also been resolved. By checking the
676	last comment we see the solution and know what to do in order to resolve it.	708	last comment we see the solution and know what to do in order to resolve it.
677	Now, let's see what would have happened if we had not used the advanced search:	709	Now, let's see what would have happened if we had not used the advanced search.
678	</p>	710	</p>
679		711
680	<figure link="/images/docs/bugzie-basic-search-result.png" caption="Basic Search Results"/>	712	<figure link="/images/docs/bugzie-basic-search-result.png" caption="Basic Search Results"/>
681		713
682	<p>	714	<p>
…		…
713	</p>	745	</p>
714		746
715	<figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/>	747	<figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/>
716		748
717	<p>	749	<p>
718	Go ahead and click on "Report a Bug - Using the Guided format".	750	Click on "Report a Bug - Using the guided format".
719	</p>	751	</p>
720		752
721	<figure link="/images/docs/bugzie-prod-select.png" caption="Product Selection"/>	753	<figure link="/images/docs/bugzie-prod-select.png" caption="Product Selection"/>
722		754
723	<p>	755	<p>
724	As you can see, <b>major</b> emphasis has been placed on putting your bug in the	756	As you can see, <b>major</b> emphasis has been placed on putting your bug in the
725	right place. Gentoo Linux is where a large majority of bugs go. Despite this,	757	right place. Gentoo Linux is where a large majority of bugs go.
		758	</p>
		759
		760	<p>
726	some people will file ebuild bugs in portage development (assumption that	761	Despite this, some people will file ebuild bugs in portage development
727	portage team handles the portage tree) or infra (assumption that infra has	762	(assumption that portage team handles the portage tree) or infra (assumption
728	access to mirrors and rsync and can fix it directly). This is simply not how	763	that infra has access to mirrors and rsync and can fix it directly). This is
729	things work. Our bug goes in Gentoo Linux, as it's an ebuild bug. We head over	764	simply not how things work.
730	there and are presented with the multi-step bug reporting process.	765	</p>
		766
		767	<p>
		768	Another common misconception occurs with our Documentation bugs. For example, a
		769	user finds a bug with the <uri link="/proj/en/releng/catalyst/">Catalyst
		770	Docs</uri>. The general tendency is to file a bug under Docs-user, which gets
		771	assigned to the <uri link="http://gdp.gentoo.org">GDP</uri>, when it should
		772	actually go to a member of the <uri link="/proj/en/releng/">Release
		773	Engineering</uri> team. As a rule of thumb, only documentation under
		774	<path>http://www.gentoo.org/doc/*</path> is under the GDP. Anything under
		775	<path>http://www.gentoo.org/proj/*</path> is under the respective teams.
731	</p>	776	</p>
732		777
733	<note>	778	<note>
734	We would rather see a non-Gentoo Linux bug filed in Gentoo Linux than a Gentoo	779	We would rather see a bug whose product was not supposed to be Gentoo Linux but
735	Linux bug filed in non-Gentoo Linux projects! While neither is preferred, the	780	has been filed under the same rather than seeing a bug which belongs the Gentoo
		781	Linux product and filed elsewhere. While neither is preferred, the former is
736	former is more acceptable and understandable (except website bugs.. we might	782	more acceptable and understandable (except website bugs.. we might have an issue
737	have an issue with that...)	783	with that...).
738	</note>	784	</note>
739		785
740	<p>	786	<p>
741	Let us now proceed with Step 1...	787	Our bug goes in Gentoo Linux as it's an ebuild bug. We head over there and are
		788	presented with the multi-step bug reporting process. Let us now proceed with
		789	Step 1...
742	</p>	790	</p>
743		791
744	<figure link="/images/docs/bugzie-guide-step1.png" caption="Guided Format Step 1"/>	792	<figure link="/images/docs/bugzie-guide-step1.png" caption="Guided Format Step 1"/>
745		793
746	<p>	794	<p>
747	The first step here is really important (as the red text tells you). This is	795	The first step here is really important (as the red text tells you). This is
748	where you search to see that someone else hasn't hit the same bug you have, yet.	796	where you search to see that someone else hasn't hit the same bug you have, yet.
749	If you do skip this step, and a bug like yours already exists, it will be marked	797	If you do skip this step and a bug like yours already exists, it will be marked
750	as a DUPLICATE thus wasting a large amount of QA effort. To give you an idea,	798	as a DUPLICATE thus wasting a large amount of QA effort. To give you an idea,
751	the numbers that are struck out above are duplicate bugs. Now comes step 2,	799	the bug numbers that are struck out above are duplicate bugs. Now comes step 2,
752	where we give the information.	800	where we give the information.
753	</p>	801	</p>
754		802
755	</body>	803	</body>
756	</section>	804	</section>
757	<section>	805	<section>
758	<title>Required Information</title>	806	<title>Required Information</title>
759	<body>	807	<body>
760		808
761	<p>
762	Onto Step 2, let's see what we have here.
763	</p>
764
765	<figure link="/images/docs/bugzie-basic.png" caption="Basic Information"/>	809	<figure link="/images/docs/bugzie-basic.png" caption="Basic Information"/>
766		810
767	<p>	811	<p>
768	First, there's the product. This is Gentoo Linux, which we selected earlier.	812	Let us take a closer look at what's what.
769	Component is where the problem occurs. We use this to help us sort out the	813	</p>
770	severity of the issue (i.e. baselayout and core systems will be more important	814
771	than new ebuilds or application bugs). Here we select Application, as it is an	815	<ul>
772	application at fault. Hardware platform is what architecture you're running.	816	<li>
773	If you were running SPARC, you would set it to SPARC. For this example, we know	817	First, there's the Product. The product will narrow down the bug to a
774	this error can occur on multiple architectures, so we'll select All. Operating	818	specific area of Gentoo like Bugzilla (for bugs relating to
775	System is what Operating System you're using. Because Gentoo is considered a	819	bugs.gentoo.org), Docs-user(for User Documentation) or Gentoo Linux (for
		820	ebuilds and the like).
		821	</li>
		822	<li>
		823	Component is where exactly the problem occurs, more specifically which part
		824	of selected product the bug comes under. This makes classification easier.
		825	</li>
		826	<li>
		827	Hardware platform is what architecture you're running. If you were running
		828	SPARC, you would set it to SPARC.
		829	</li>
		830	<li>
		831	Operating System is what Operating System you're using. Because Gentoo is
776	"Meta-distribution", it can run on other operating systems beside Linux.	832	considered a "Meta-distribution", it can run on other operating systems
777	Examples are Gentoo on MacOS, Gentoo on FreeBSD, etc. For this example,	833	beside Linux.
778	we'll select All, as this can occur on all types of systems. Build Identifier	834	</li>
779	is what is being used to report the bugs (for logging purposes). You can just	835	</ul>
780	leave this as is. Let's see what we have so far:	836
781	</p>	837	<p>
		838	So, for our example bug, we have :
		839	</p>
		840
		841	<ul>
		842	<li>Product - Gentoo Linux (Since it is an ebuild issue)</li>
		843	<li>Component - Application (It is an application at fault, foobar2)</li>
		844	<li>Hardware Platform - All (This error could occur across architectures)</li>
		845	<li>Operation System - All (It could occur on all types of systems)</li>
		846	</ul>
782		847
783	<figure link="/images/docs/bugzie-basic-comp.png" caption="Completed Basic Information"/>	848	<figure link="/images/docs/bugzie-basic-comp.png" caption="Completed Basic Information"/>
784		849
785	<p>	850	<ul>
786	That does look good, so we'll begin with the actual report. In this instance,	851	<li>
787	we'll use the foobar2 bug as our example. URL is used to point to errors on a	852	Build Identifier is basically the User Agent of the browser that is being
788	site someplace (pastebin, etc.). However, doing it inside the bug allows the	853	used to report the bugs (for logging purposes). You can just leave this as
789	developers be able to reference to it at any time and is preferred. Then we have	854	is.
		855	</li>
		856	<li>
		857	URL is optional and is used to point to relevant information on another site
		858	(upstream bugzilla, release notes on package homepage etc.). You should
		859	never use URL to point to pastebins for error messages, logs, <c>emerge
		860	--info</c> output, screenshots or similar information. Instead, these should
		861	always be attached to the bug.
		862	</li>
		863	<li>
790	the summary. In the summary, you should put the package category, name, and	864	In the Summary, you should put the package category, name, and number.
		865	</li>
		866	</ul>
		867
		868	<p>
791	number. Not including the category really isn't too bad, but it's recommended.	869	Not including the category in the summary really isn't too bad, but it's
792	If you don't include the package name, however, we won't know what you're	870	recommended. If you don't include the package name, however, we won't know what
793	filling a bug for, and will have to ask you about it later. The version number	871	you're filling a bug for, and will have to ask you about it later. The version
794	is important for people searching for bugs. If 20 people filed bugs and not one	872	number is important for people searching for bugs. If 20 people filed bugs and
795	put a version number, how would people looking for similar bugs be able to tell	873	not one put a version number, how would people looking for similar bugs be able
796	if one was there's? They'd have to look through every single bug, which isn't	874	to tell if one was there's? They'd have to look through every single bug, which
797	too hard, but if there are say, 200 bugs.. it's not that easy. After all the	875	isn't too hard, but if there are say, 200 bugs.. it's not that easy. After all
798	package information, you'll want to include a small description of the incident.	876	the package information, you'll want to include a small description of the
799	Here's an example:	877	incident. Here's an example:
800	</p>	878	</p>
801		879
802	<figure link="/images/docs/bugzie-summary.png" caption="Summary"/>	880	<figure link="/images/docs/bugzie-summary.png" caption="Summary"/>
803		881
804	<p>	882	<p>
805	Just these simple rules can make handling bugs a lot easier. Next are the	883	These simple rules can make handling bugs a lot easier. Next are the details.
806	details. Here we put in the information about the bug. We'll demonstrate with an	884	Here we put in the information about the bug. We'll demonstrate with an example:
807	example:
808	</p>	885	</p>
809		886
810	<figure link="/images/docs/bugzie-details.png" caption="Details"/>	887	<figure link="/images/docs/bugzie-details.png" caption="Details"/>
811		888
812	<p>	889	<p>
813	So now the developer knows why we're filing the bug. They can then try to	890	Now the developer knows why we're filing the bug. They can then try to
814	reproduce it. Reproducibility tells us how often we were able to make the	891	reproduce it. Reproducibility tells us how often we were able to make the
815	problem recur. In this example, we can reproduce it any time simply by running	892	problem recur. In this example, we can reproduce it any time simply by running
816	foobar2. Let's put that information in:	893	foobar2. Let's put that information in.
817	</p>	894	</p>
818		895
819	<figure link="/images/docs/bugzie-reprod.png" caption="Reproduction"/>	896	<figure link="/images/docs/bugzie-reprod.png" caption="Reproduction"/>
820		897
821	<p>	898	<p>
822	So now we have explained how we found the bug. Next we want to explain what	899	We have explained how we found the bug. The next step is to explain what were
823	the results were and what we think they should be:	900	the results we got and what we think they should actually be.
824	</p>	901	</p>
825		902
826	<figure link="/images/docs/bugzie-results.png" caption="Results"/>	903	<figure link="/images/docs/bugzie-results.png" caption="Results"/>
827		904
828	<p>	905	<p>
829	Next we put additional information. This can be things such as stack traces,	906	We could then provide additional information. This could be things such as
		907	stack traces, <b>sections</b> (since the whole log is usually big and of not
830	<b>sections</b> of strace logs, but most importantly, your emerge --info output.	908	much use) of strace logs, but most importantly, your <c>emerge --info</c>
831	Here's an example:	909	output. Here's an example.
832	</p>	910	</p>
833		911
834	<figure link="/images/docs/bugzie-addl-info.png" caption="Additional Information"/>	912	<figure link="/images/docs/bugzie-addl-info.png" caption="Additional Information"/>
835		913
836	<p>	914	<p>
837	Lastly we select the severity of the bug. Please look this over carefully. In	915	Lastly we select the severity of the bug. Please look this over carefully. In
838	most cases it's OK to leave it as is and someone will raise/lower it for you.	916	most cases it's OK to leave it as is and someone will raise/lower it for you.
839	However, if you raise the severity of the bug, please make sure you read it over	917	However, if you raise the severity of the bug, please make sure you read it over
840	carefully and make sure you're not making a mistake. Here we will set it to the	918	carefully and make sure you're not making a mistake. A run down of the various
841	default of normal:	919	levels is given below.
842	</p>	920	</p>
		921
		922	<ul>
		923	<li>
		924	Blocker - The program just plain doesn't want to emerge or is a major
		925	hinderance to the system. For example a <c>baselayout</c> issue which
		926	prevents a system from booting up would be a sure candidate to be labelled
		927	blocker.
		928	</li>
		929	<li>
		930	Critical - The program has loss of data or severe memory leaks during
		931	runtime. Again, an important program like say <c>net-tools</c> failing to
		932	compile could be labelled critical. It won't prevent the system from
		933	starting up, but is quite essential for day to day stuff.
		934	</li>
		935	<li>
		936	Major - The program crashes, but nothing that causes your system severe
		937	damage or information loss.
		938	</li>
		939	<li>
		940	Minor - Your program crashes here and there with apparent workarounds.
		941	</li>
		942	<li>
		943	Normal - The default. If you're not sure leave it here unless it's a new
		944	build or cosmetic change, then read below for more information.
		945	</li>
		946	<li>Trivial - Things such as a mispelled word or whitespace clean up. </li>
		947	<li>
		948	Enhancement - A request to enable a new feature in a program, or more
		949	specifically <e>new ebuilds</e>.
		950	</li>
		951	</ul>
843		952
844	<figure link="/images/docs/bugzie-sev.png" caption="Severity"/>	953	<figure link="/images/docs/bugzie-sev.png" caption="Severity"/>
		954
		955	<p>
		956	Here, we'll set it to Normal.
		957	</p>
845		958
846	<p>	959	<p>
847	Now we can submit the bug report by clicking on the Submit Bug Report box. You	960	Now we can submit the bug report by clicking on the Submit Bug Report box. You
848	will now see your new bug come up. See <uri	961	will now see your new bug come up. See <uri
849	link="https://bugs.gentoo.org/show_bug.cgi?id=97265">Bug 97561</uri> for what	962	link="https://bugs.gentoo.org/show_bug.cgi?id=97265">Bug 97561</uri> for what
…		…
851	with.	964	with.
852	</p>	965	</p>
853		966
854	</body>	967	</body>
855	</section>	968	</section>
		969	<section>
		970	<title>Zero-day bump requests</title>
		971	<body>
		972
		973	<p>
		974	So far, we've shown what to do when filing a bug. Now let's take a look at what
		975	<e>not</e> to do.
		976	</p>
		977
		978	<p>
		979	Suppose that you've eagerly been following an upstream project's schedule, and
		980	when you check their homepage, guess what? They just released a new version a
		981	few minutes ago! Most users would immediately rush over to Gentoo's bugzilla to
		982	report the new version is available; please bump the existing version and add
		983	it to Portage, etc. However, this is exactly what you should <b>not</b> do.
		984	These kinds of requests are called zero-day (or 0-day) bump requests, as they're
		985	made the same day that a new version is released.
		986	</p>
		987
		988	<impo>
		989	<b>Please wait <e>at least</e> 48 hours before reporting a new release on our
		990	bugzilla.</b> Also, you <e>must</e> check bugzilla before posting your request
		991	to make sure that someone else hasn't already reported it, or that the Gentoo
		992	maintainers haven't already dealt with the new version.
		993	</impo>
		994
		995	<p>
		996	Why should you wait? First, it's quite rude to demand that Gentoo developers
		997	drop everything they're doing just to add a new release that came out 15 minutes
		998	ago. Your zero-day bump request could be marked as INVALID or LATER, as
		999	developers have plenty of pressing issues to keep them busy. Second, developers
		1000	are usually aware of pending new releases well in advance of users, as they must
		1001	follow upstream quite closely. They already know a new version is on its way.
		1002	In many cases, they will have already opened a bug, or might even already added
		1003	it in Portage as a masked package.
		1004	</p>
		1005
		1006	<p>
		1007	Be smart when testing and requesting new versions of packages. Search bugzilla
		1008	before posting your bump request -- is there already a bug open? Have you synced
		1009	lately; is it already in Portage? Has it actually been released by upstream?
		1010	Basic common sense will go a long way, and will endear you to developers that
		1011	already have a lot to do. If it's been several days since release and you're
		1012	sure that there are no open requests for it (and that it's not in Portage), then
		1013	you can open up a new bug. Be sure to mention that it compiles and runs well on
		1014	your arch. Any other helpful information you provide is most welcome.
		1015	</p>
		1016
		1017	<p>
		1018	Want to see the newest version of your favorite package in Portage? File smart
		1019	bugs.
		1020	</p>
		1021
		1022	</body>
		1023	</section>
856	</chapter>	1024	</chapter>
857		1025
858	<chapter>	1026	<chapter>
859	<title>Working With Your Bug</title>	1027	<title>Working With Your Bug</title>
860	<section>	1028	<section>
861	<body>	1029	<body>
862		1030
863	<p>	1031	<p>
864	looking at the bug, we see the information we provided earlier:	1032	Looking at the bug, we see the information we provided earlier. You will notice
		1033	that the bug has been assigned to bug-wranglers@gentoo.org. This is the default
		1034	location for Application component bugs.
865	</p>	1035	</p>
866		1036
867	<figure link="/images/docs/bugzie-new-basic.png" caption="New Bug Basic Information"/>	1037	<figure link="/images/docs/bugzie-new-basic.png" caption="New Bug Basic Information"/>
868		1038
869	<p>	1039	<p>
870	And our details are there too:	1040	The details we entered about the bug are available as well.
871	</p>	1041	</p>
872		1042
873	<figure link="/images/docs/bugzie-new-details.png" caption="New Bug Details"/>	1043	<figure link="/images/docs/bugzie-new-details.png" caption="New Bug Details"/>
874		1044
875	<p>	1045	<p>
876	Now as you can see, the bug has been assigned to bug-wranglers@gentoo.org. This	1046	However, bug-wranglers (usually) won't fix our bugs, so we'll reassign it to
877	is the default location for Application component bugs. However, bug-wranglers	1047	someone that can (you can let bug-wranglers re-assign it for you as well). For
878	(usually) won't fix our bugs, so we'll reassign it to someone that can (you can
879	let bug-wranglers re-assign it for you as well). For this we use the package's
880	metadata.xml. You can normally find them in	1048	this we use the package's metadata.xml. You can normally find them in
881	/usr/portage/category/package/metadata.xml. Here's one I've made up for foobar2:	1049	<path>/usr/portage/category/package/metadata.xml</path>. Here's one I've made up
		1050	for foobar2.
882	</p>	1051	</p>
		1052
		1053	<note>
		1054	You have to be the reporter of the bug or a member of certain Gentoo Bugzilla
		1055	groups (like Gentoo Developers) to be able to reassign bugs.
		1056	</note>
883		1057
884	<pre caption="metadata.xml">	1058	<pre caption="metadata.xml">
885	<?xml version="1.0" encoding="UTF-8"?>	1059	<?xml version="1.0" encoding="UTF-8"?>
886	<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">	1060	<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
887	<pkgmetadata>	1061	<pkgmetadata>
…		…
895	</longdescription>	1069	</longdescription>
896	</pkgmetadata>	1070	</pkgmetadata>
897	</pre>	1071	</pre>
898		1072
899	<p>	1073	<p>
900	Notice the maintainer section.T his lists the maintainer of the package, which	1074	Notice the maintainer section. This lists the maintainer of the package, which
901	in this case is myself, Chris White. The email listed is chriswhite@gentoo.org.	1075	in this case is myself, Chris White. The email listed is chriswhite@gentoo.org.
902	We will use this to re-assign the bug to the proper person. To do this, click	1076	We will use this to re-assign the bug to the proper person. To do this, click
903	the bubble next to Reassign bug to, then fill in the email:	1077	the bubble next to Reassign bug to, then fill in the email.
904	</p>	1078	</p>
905		1079
906	<note>	1080	<note>
907	A package without a metadata.xml file should be re-assigned to	1081	A bug for a package without a metadata.xml file should be re-assigned to
908	maintainer-needed@gentoo.org.	1082	maintainer-needed@gentoo.org and a package that needs a Gentoo Developer to
		1083	maintain should be assigned to maintainer-wanted@gentoo.org.
909	</note>	1084	</note>
910		1085
911	<figure link="/images/docs/bugzie-reassign.png" caption="Bug Reassignment"/>	1086	<figure link="/images/docs/bugzie-reassign.png" caption="Bug Reassignment"/>
912		1087
913	<p>	1088	<p>
…		…
920	</p>	1095	</p>
921		1096
922	<figure link="/images/docs/bugzie-new-attach.png" caption="New Attachment"/>	1097	<figure link="/images/docs/bugzie-new-attach.png" caption="New Attachment"/>
923		1098
924	<p>	1099	<p>
925	Now we have to attach the log. We click on the "Browse..." button under "File"	1100	Now we have to attach the log. Let's go throught it step wise.
926	and select the strace log. For Description, we'll put "strace log". Content-Type	1101	</p>
927	is what kind of file we're attaching. A common mistake is to set it to	1102
928	auto. In most cases it's best to manually set it. Our log file is a	1103	<ul>
929	plain text file, so we select "plain text (text/plain)". Obsoletes are for when	1104	<li>
930	you are attaching a revision to a previously attached file. You can simply click	1105	File - This is the location of the file in your machine. In this example,
931	a check box next to the old file and Bugzilla will cross it out in the bug,	1106	the location of <path>strace.log</path>. You can use the "Browse..." button
932	indicating that the attachment has been obsoleted. Reassignment means you want	1107	to select the file, or enter the path directly in the text field.
933	to take the bug yourself. I rarely tend to use this.. and I don't think you will	1108	</li>
934	need to at some point (unless you create great patches and we don't care about	1109	<li>
935	you taking our bugs ;). Comments are for leaving comments about the file you're	1110	Description - A short one liner, or a few wors describing the attachment.
936	posting. We'll put "Here is the strace file you requested". Now we have	1111	We'll just enter strace.log here, since that's quite self-explanatory.
937	something like this:	1112	</li>
		1113	<li>
		1114	Content Type - This is the type of the file we're attaching to the bug.
		1115	</li>
		1116	<li>
		1117	Obsoletes - If there were attachements submitted to the bug before the
		1118	current one, you have an option of declaring them obsoleted by yours. Since
		1119	we have no prior attachments to this bug, we need not bother.
		1120	</li>
		1121	<li>
		1122	Comment - Enter comments that will be visible along with the attachments.
		1123	You could elaborate on the attachment here, if needed.
		1124	</li>
		1125	</ul>
		1126
938	</p>	1127	<p>
		1128	With respect to Content Type, here are a few more details. You can check the
		1129	"patch" checkbox if you're submitting a patch. Otherwise, you could ask
		1130	Bugzilla to "auto-detect" the file type (not advisable). The other options are
		1131	"select from list", which is most frequently used. Use plain text (text/plain)
		1132	for <e>most</e> attachments except binary files like images (which can use
		1133	image/gif, image/jpeg or image/png depending on type) or compressed files like
		1134	.tar.bz2 which would use application/octet-stream as content type.
		1135	</p>
		1136
939		1137
940	<figure link="/images/docs/bugzie-new-attach-comp.png" caption="New Attachment Completed"/>	1138	<figure link="/images/docs/bugzie-new-attach-comp.png" caption="New Attachment Completed"/>
941		1139
942	<p>	1140	<p>
943	We Submit the patch and it is now reflected on the bug report.	1141	We submit <path>strace.log</path> and it is reflected on the bug report.
944	</p>	1142	</p>
945		1143
946	<figure link="/images/docs/bugzie-strace.png" caption="Attached strace log"/>	1144	<figure link="/images/docs/bugzie-strace.png" caption="Attached strace log"/>
947		1145
948	<p>	1146	<p>
949	Now, while we're waiting another person notices your bug during step 1 of the	1147	We've mentioned before that sometimes ebuilds will tell you to attach a file in
950	Guided Format. This person wants to see the status of the bug as well. He or	1148	the emerge error. An example can be seen below.
		1149	</p>
		1150
		1151	<pre caption="Example File Attachment Request">
		1152	configure: error: PNG support requires ZLIB. Use --with-zlib-dir=<DIR>
		1153
		1154	!!! Please attach the config.log to your bug report:
		1155	!!! /var/tmp/portage/php-5.0.3-r1/work/php-5.0.3/config.log
		1156
		1157	!!! ERROR: dev-php/php-5.0.3-r1 failed.
		1158	!!! Function econf, Line 485, Exitcode 0
		1159	!!! econf failed
		1160	!!! If you need support, post the topmost build error, NOT this status message.
		1161	</pre>
		1162
		1163	<p>
		1164	Please attach any file mentioned like this to your bug report.
		1165	</p>
		1166
		1167	<p>
		1168	Sometimes a developer might ask you to attach a diff or patch for a file.
		1169	Standard diff files can be obtained through:
		1170	</p>
		1171
		1172	<pre caption="Standard Diff Creation">
		1173	$ <i>cp file file.old</i>
		1174	$ <i>nano file</i>
		1175	$ <i>diff -u file.old file</i>
		1176	</pre>
		1177
		1178	<p>
		1179	For C/C++ source files, the <b>-p</b> flag is added to show what function calls
		1180	the diff applies to:
		1181	</p>
		1182
		1183	<pre caption="Diff-ing C/C++ source">
		1184	$ <i>cp file.c file.c.old</i>
		1185	$ <i>nano file.c</i>
		1186	$ <i>diff -up file.c.old file.c</i>
		1187	</pre>
		1188
		1189	<p>
		1190	The documentation team will require the flag combination <b>-Nt</b> as well as
		1191	<b>-u</b>. This mainly has to do with tab expansion. You can create such a diff
		1192	with:
		1193	</p>
		1194
		1195	<pre caption="Documentation diffs">
		1196	$<i> cp file.xml file.xml.old</i>
		1197	$<i> nano file.xml</i>
		1198	$<i> diff -Nut file.xml.old file.xml</i>
		1199	</pre>
		1200
		1201	<p>
		1202	And your diff is created. While we're doing all this, suppose another person
		1203	finds your bug by searching through bugzilla and is curious to keep track of
951	she may do so by putting their email in the Add CC field like so:	1204	the bug, they may do so by putting their email in the Add CC field of the bug
		1205	as shown below. You could also keep track of other bugs by following the same
		1206	method.
952	</p>	1207	</p>
953		1208
954	<figure link="/images/docs/bugzie-add-email.png" caption="Adding Email To CC:"/>	1209	<figure link="/images/docs/bugzie-add-email.png" caption="Adding Email To CC:"/>
955		1210
956	<note>	1211	<note>
957	Email addresses must be registered with bugzilla. In order to CC multiple	1212	Email addresses must be registered with Gentoo Bugzilla. In order to CC multiple
958	addresses, simply separate them with commas or spaces.	1213	addresses, simply separate them with commas or spaces.
959	</note>	1214	</note>
960		1215
961	<p>	1216	<p>
962	After all this work, the bug can undergo various status markings. Here's a few:	1217	After all this work, the bug can undergo various status markings. This is
		1218	usually done by the Gentoo Developers and sometimes by the reporter. The
		1219	following are the various possible states a bug may go through during its
		1220	lifetime.
963	</p>	1221	</p>
964		1222
965	<ul>	1223	<ul>
966	<li>	1224	<li>
967	UNCONFIRMED - You're generally not going to see this too often. This	1225	UNCONFIRMED - You're generally not going to see this too often. This means
968	means that a bug reporter has opened a bug using the advanced method and is	1226	that a bug reporter has opened a bug using the advanced method and is
969	uncertain his or her bug is an actual bug.	1227	uncertain his or her bug is an actual bug.
970	</li>
971	<li>	1228	</li>
972	NEW - Bugs that are first opened are considered new.	1229	<li>NEW - Bugs that are first opened are considered new.</li>
973	</li>
974	<li>	1230	<li>
975	ASSIGNED - When the person you've assigned the bug too validates your	1231	ASSIGNED - When the person you've assigned the bug too validates your bug,
976	bug, it will often receive ASSIGNED status while they figure out the issue.	1232	it will often receive ASSIGNED status while they figure out the issue.
977	This let's you know that they've accepted your bug as a real bug.	1233	This lets you know that they've accepted your bug as a real bug.
978	</li>
979	<li>	1234	</li>
		1235	<li>
980	REOPENED - Someone has resolved a bug and you think the solution is not	1236	REOPENED - Someone has resolved a bug and you think the solution is not
981	feasible or the problem still persists. At this point, you may re-open the	1237	feasible or the problem still persists. At this point, you may re-open the
982	bug. However <b>please do not abuse this</b>. If a developer closes the bug a	1238	bug. Please <b>do not abuse this</b>. If a developer closes the bug a
983	second or even third time, chances are that your bug is closed.	1239	second or third time, chances are that your bug is closed.
984	</li>	1240	</li>
		1241	<li>
		1242	RESOLVED - A firm decision has been taken on the bug. Usually goes onto
		1243	FIXED to indicate the bug is solved and the matter closed although various
		1244	other resolutions are possible. We'll look into those a little later.
		1245	</li>
		1246	<li>
		1247	VERIFIED - The steps take to work the bug are correct. This is usually a QA
		1248	thing.
		1249	</li>
		1250	<li>
		1251	CLOSED - Basically means RIP for the bug and it's buried under the never
		1252	ending flow of new bugs.
		1253	</li>
985	</ul>	1254	</ul>
986		1255
987	<p>	1256	<p>
988	Now shortly afterward, I find the error in the strace log. I resolve the bug	1257	Now shortly afterward, we find the error in the strace log and fix the bug and
989	as RESOLVED FIXED and say that there was a change in the location of	1258	mark it as RESOLVED FIXED and mention that there was a change in the location
990	configuration files, and that I will update the ebuild with a warning about it.	1259	of configuration files, and that I will update the ebuild with a warning about
991	The bug now becomes resolved, and you are displayed with this:	1260	it. The bug now becomes resolved, and you are shown the following.
992	</p>	1261	</p>
993		1262
994	<figure link="/images/docs/bugzie-reso.png" caption="Resolved Bug"/>	1263	<figure link="/images/docs/bugzie-reso.png" caption="Resolved Bug"/>
995		1264
996	<p>	1265	<p>
997	Also note the section here:	1266	A little below, you'll see the following:
998	</p>	1267	</p>
999		1268
1000	<figure link="/images/docs/bugzie-options.png" caption="Bug Options"/>	1269	<figure link="/images/docs/bugzie-options.png" caption="Bug Options"/>
1001		1270
1002	<p>	1271	<p>
1003	This gives you the option of Reopening the bug if you wish to (i.e. the developer	1272	This gives you the option of Reopening the bug if you wish to (i.e. the
1004	thinks it's resolved but it's really not to your standards). Now our bug is	1273	developer thinks it's resolved but it's really not to your standards). Now our
1005	fixed! However, different resolutions can occur. Here's a small list:	1274	bug is fixed! However, different resolutions can occur. Here's a small list:
1006	</p>	1275	</p>
1007		1276
1008	<ul>	1277	<ul>
1009	<li>	1278	<li>
1010	FIXED - The bug is fixed, follow the instructions to resolve your	1279	FIXED - The bug is fixed, follow the instructions to resolve your issue.
1011	issue.
1012	</li>
1013	<li>	1280	</li>
		1281	<li>
1014	INVALID - You did not do something specifically documented, causing the	1282	INVALID - You did not do something specifically documented, causing the
1015	bug	1283	bug.
1016	</li>
1017	<li>	1284	</li>
1018	DUPLICATE - You didn't use this guide and reported a duplicate bug	1285	<li>DUPLICATE - You didn't use this guide and reported a duplicate bug.</li>
1019	:)	1286	<li>
1020	</li>	1287	WORKSFORME - Developer/person assigned the bug cannot reproduce your error.
1021	<li>	1288	</li>
1022	WORKSFORME - Developer/person assigned the bug cannot reproduce your	1289	<li>
1023	error	1290	CANTFIX - Somehow the bug cannot be solved because of certain
		1291	circumstances. These circumstances will be noted by the person taking the
		1292	bug.
1024	</li>	1293	</li>
		1294	<li>
		1295	WONTFIX - This is usually applied to new ebuilds or feature requests.
		1296	Basically the developer does not want to add a certain feature because it
		1297	is not needed, a better alternative exists, or it's just plain broken.
		1298	Sometimes you may be given a solution to get said issue resolved.
		1299	</li>
		1300	<li>
		1301	UPSTREAM - The bug cannot be fixed by the Gentoo development team, and have
		1302	requested you take the problem upstream (the people that actually made the
		1303	program) for review. Upstream has a few ways of handling bugs. These
		1304	include mailing lists, irc channels, and even bug reporting systems. If
		1305	you're not sure how to contact them, ask in the bug and someone will point
		1306	you to the right direction.
		1307	</li>
1025	</ul>	1308	</ul>
1026		1309
		1310	<p>
		1311	Sometimes, before the bug can be resolved, a developer may request that you
		1312	test an updated ebulid. In the next chapter we'll take a look at testing
		1313	ebuilds.
		1314	</p>
		1315
1027	</body>	1316	</body>
		1317	</section>
		1318	</chapter>
		1319
		1320	<chapter>
		1321	<title>Testing Ebuilds</title>
1028	</section>	1322	<section>
		1323	<title>Getting The Files</title>
		1324	<body>
1029		1325
		1326	<p>
		1327	Let's say that you reported a bug for the foobar2 compile fix from earlier. Now
		1328	developers might find out what the problem is and might need you to test the
		1329	ebuild for them to be sure it works for you as well:
		1330	</p>
		1331
		1332	<figure link="/images/docs/bugzie-ebuild-request.png" caption="Ebuild Test Request"/>
		1333
		1334	<p>
		1335	Some rather confusing vocabulary is used here. First off, let's see what an
		1336	overlay is. An overlay is a special directory like <path>/usr/portage</path>,
		1337	the difference being that when you <c>emerge sync</c>, files contained within it
		1338	will not be deleted. Luckily, a special <path>/usr/local/portage</path>
		1339	directory is created for that purpose. Let's go ahead and set our portage
		1340	overlay in<path>/etc/make.conf</path>. Open make.conf up in your favorite editor
		1341	and add this towards the end.
		1342	</p>
		1343
		1344	<pre caption="Setting Up PORTDIR_OVERLAY">
		1345	PORTDIR_OVERLAY="/usr/local/portage"
		1346	</pre>
		1347
		1348	<p>
		1349	Now we'll want to create the appropriate directories to put our test ebuild
		1350	files in. In this case, we're supposed to put them in sys-apps/foobar2. You'll
		1351	notice that the second comment asks for a <path>files</path> directory for the
		1352	patch. This directory holds other required files that aren't included with
		1353	the standard source archive (patches, init.d scripts, etc). This is a subdir in
		1354	the package directory called <path>files</path>. Go ahead and create these
		1355	directories:
		1356	</p>
		1357
		1358	<pre caption="Setting Up The Category And Package Directories">
		1359	# <i>mkdir -p /usr/local/portage/sys-apps/foobar2/files</i>
		1360	</pre>
		1361
		1362	<note>
		1363	The -p in mkdir creates not only the directory you want but also any missing
		1364	parent directories as well (sys-apps and foobar2 in this case).
		1365	</note>
		1366
		1367	<p>
		1368	Ok now, we can go ahead and download the files. First, download the ebuild
		1369	into <path>/usr/local/portage/sys-apps/foobar2</path>, and then add the patch
		1370	to <path>/usr/local/portage/sys-apps/foobar2/files</path>. Now that we have the
		1371	files, we can begin working on testing the ebuild.
		1372	</p>
		1373
		1374	</body>
		1375	</section>
		1376	<section>
		1377	<title>Testing The ebuild</title>
		1378	<body>
		1379
		1380	<p>
		1381	The process to create an ebuild that can be used by emerge is fairly simple. You
		1382	must create a Manifest file for the ebuild. This can be done with
		1383	the ebuild command. Run it as shown.
		1384	</p>
		1385
		1386	<pre caption="Creating the Manifest file">
		1387	# <i>ebuild foobar2-1.0.ebuild manifest</i>
		1388	>>> Creating Manifest for /usr/local/portage/sys-apps/foobar2
		1389	</pre>
		1390
		1391	<p>
		1392	Now let's test to see if it works as it should.
		1393	</p>
		1394
		1395	<pre caption="Testing With emerge -pv">
		1396	# <i>emerge -pv foobar2</i>
		1397
		1398	These are the packages that I would merge, in order:
		1399
		1400	Calculating dependencies ...done!
		1401	[ebuild N ] sys-apps/foobar2-1.0 0 kB [1]
		1402
		1403	Total size of downloads: 0 kB
		1404	Portage overlays:
		1405	[1] /usr/local/portage
		1406	</pre>
		1407
		1408	<p>
		1409	It does seem to have worked! You'll notice the [1] next to the [ebuild] line.
		1410	That points to <path>/usr/local/portage</path>, which is the overlay we created
		1411	earlier. Now we go ahead and emerge the package.
		1412	</p>
		1413
		1414	<pre caption="Emerge Result">
		1415	# <i>emerge foobar2</i>
		1416	Calculating dependencies ...done!
		1417	<comment>(compile info snipped)</comment>
		1418	>>> Unpacking foobar2-1.0.tar.bz2 to /var/tmp/portage/foobar2-1.0/work
		1419	* Applying foobar2-1.0-Makefile.patch ... [ ok ]
		1420	<comment>(compile info snipped)</comment>
		1421	>>> Merging sys-apps/foobar2-1.0 to /
		1422	>>> chris +sandbox(preinst)
		1423	--- /usr/
		1424	--- /usr/bin/
		1425	>>> /usr/bin/foobar2
		1426	</pre>
		1427
		1428	<p>
		1429	In the first section we see that the emerge started off as it should. The second
		1430	section shows our patch being applied successfully by the "[ ok ]" status
		1431	message to the right. The last section tells us the program compiled ok. The
		1432	patch works! Now we can go and let the developer know that their patch works
		1433	fine, and that they can commit the fix to portage.
		1434	</p>
		1435
		1436	</body>
		1437	</section>
1030	<section>	1438	<section>
1031	<title>Conclusion</title>	1439	<title>Conclusion</title>
1032	<body>	1440	<body>
1033		1441
1034	<p>	1442	<p>
1035	This concludes the howto on working with Bugzilla. I hope you find this useful.	1443	This concludes the howto on working with Bugzilla. I hope you find this useful.
1036	If you have any questions, comments, or ideas regarding this document, please	1444	If you have any questions, comments, or ideas regarding this document, please
1037	send them to me at <mail	1445	send them to me at <mail>chriswhite@gentoo.org</mail>. Special thanks go to
1038	link="chriswhite@gentoo.org">chriswhite@gentoo.org</mail>. Special
1039	thanks go to moreon for his notes on -g flags and compile errors, the people at	1446	moreon for his notes on -g flags and compile errors, the people at #gentoo-bugs
1040	#gentoo-bugs for helping out with bug-wrangling, and Griffon26 for his notes on	1447	for helping out with bug-wrangling, Griffon26 for his notes on
1041	maintainer-needed.	1448	maintainer-needed, robbat2 for general suggestions and fox2mike for fixing up
		1449	the doc and adding stuff as needed.
1042	</p>	1450	</p>
1043		1451
1044	</body>	1452	</body>
1045	</section>	1453	</section>
1046	</chapter>	1454	</chapter>

 Legend:



Removed from v.1.1
 


changed lines


 
Added in v.1.14
 Legend:



Removed from v.1.1
 


changed lines


 
Added in v.1.14
-Removed from v.1.1
+Added in v.1.14

	ViewVC Help
Powered by ViewVC 1.1.17