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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.3 - (hide annotations) (download) (as text)
Sat Jul 9 22:31:57 2005 UTC (9 years, 3 months ago) by fox2mike
Branch: MAIN
Changes since 1.2: +539 -210 lines
File MIME type: application/xml
Major updates to the guide. GuideXML corrections, content and grammer changes along with a few section additions. IMPORTANT : Translators, Please do not commence work on this guide for the next couple of days as the guide may see drastic changes. See gentoo-doc ML for details. Thanks.

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

  ViewVC Help
Powered by ViewVC 1.1.20