/[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.2 - (hide annotations) (download) (as text)
Thu Jul 7 18:19:23 2005 UTC (9 years, 2 months ago) by fox2mike
Branch: MAIN
Changes since 1.1: +23 -22 lines
File MIME type: application/xml
Fixed http -> https in a Bugzie link. Added a few <path> tags where needed.

1 fox2mike 1.1 <?xml version="1.0" encoding="UTF-8"?>
2     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 fox2mike 1.2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.1 2005/07/07 12:02:21 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.2 <version>1.1</version>
24 fox2mike 1.1 <date>2005-07-07</date>
25    
26     <chapter>
27     <title>Introduction</title>
28     <section>
29     <title>Preface</title>
30     <body>
31    
32     <p>
33     Often one of the factors that delay a bug being fixed is how it is reported. By
34     creating this guide, I hope to help improve the communication between
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
37     guide will help make that a success.
38     </p>
39    
40     </body>
41     </section>
42     <section>
43     <title>Initial Finding</title>
44     <body>
45    
46     <p>
47     You're emerge-ing a package or working with a program, then suddenly the worst
48     happens -- you find a bug. Bugs come in many forms, whether it be emerge
49     failures or segmentation faults. Whatever the cause, the fact still remains that
50     such a bug must be fixed. Here is a few examples of such bugs.
51     </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     you do? The following sections will look at 2 important tools for handling
91     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     errors -- <c>gdb</c>
94     </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     program is to <c>emerge</c> the program with FEATURES="nostrip". This prevents
112     the stripping of debug symbols. Why are programs stripped by default? The reason
113     is the same as that for having gzipped man pages -- saving space. Here's how the
114     size of a program varies with and without debug symbol stripping.
115     </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     the size! Two more things can be done for debugging. The first is adding -g to
129     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
131     debug to the package's USE flags. This can be done with the
132     <path>package.use</path> file.
133     </p>
134    
135     <pre caption="Using package.use to add debug USE flag">
136     # <i>echo "category/package debug" >> /etc/portage/package.use</i>
137     </pre>
138    
139     <note>
140     The directory <path>/etc/portage</path> does not exist by default and you may
141     have to create it, if you have not already done so. If the package already has
142     USE flags set in <path>package.use</path>, you will need to manually modify them
143     in your favorite editor.
144     </note>
145    
146     <p>
147     Now that that's done, you will need to re-emerge your package to set the
148     new debug settings into place. This can be done as follows:
149     </p>
150    
151     <pre caption="Re-emergeing a package with debugging">
152     # <i>FEATURES="nostrip" emerge package</i>
153     </pre>
154    
155     <p>
156     Now that debug symbols are setup, we can continue with debugging the program.
157     </p>
158    
159     </body>
160     </section>
161     <section>
162     <title>Running the program with GDB</title>
163     <body>
164    
165     <p>
166     Let's say we have a program here called "bad_code" (I know, it's sort of cheesy
167     but..). Some person claims he can break the code and provides an example. You go
168     ahead and test it out:
169     </p>
170    
171     <pre caption="Breaking The Program">
172     $ <i>./bad_code `perl -e 'print Ax100'`</i>
173     Segmentation fault
174     </pre>
175    
176     <p>
177     It seems this person was right. Since the program is obviously broken, we have
178     a bug at hand. Now, it's time to use <c>gdb</c> to help solve this matter. First
179     we run <c>gdb</c> with <c>--args</c>, then give it the full program with
180     arguments like shown:
181     </p>
182    
183     <pre caption="Running Our Program Through GDB">
184     $ <i>gdb --args ./bad_code `perl -e 'print Ax100'`</i>
185     GNU gdb 6.3
186     Copyright 2004 Free Software Foundation, Inc.
187     GDB is free software, covered by the GNU General Public License, and you are
188     welcome to change it and/or distribute copies of it under certain conditions.
189     Type "show copying" to see the conditions.
190     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".
192     </pre>
193    
194     <p>
195     You should see a small terminal like setup after that which says "(gdb)" and
196     waits for input. First, we have to run the program. We type in <c>run</c> at the
197     command and receive a notice like:
198     </p>
199    
200     <pre caption="Running the program in GDB">
201     (gdb) run
202     Starting program: /home/chris/bad_code
203    
204     Program received signal SIGSEGV, Segmentation fault.
205     0xb7ec6dc0 in strcpy () from /lib/libc.so.6
206     </pre>
207    
208     <p>
209     Here we see the program starting, as well as a notification of SIGSEGV, or
210     Segmentation Fault. This is GDB telling us that our program has crashed. It
211     also gives the last run function it could trace when the program crashes.
212     However, this isn't too useful, as there could be multiple strcpy's in the
213     program, making it hard for developers to find which one is causing the issue.
214     In order to help them out, we do what's called a backtrace. A backtrace runs
215     backwards through all the functions that occurred upon program execution, to the
216     function at fault. Functions that return (without causing a crash) will not show
217     up on the backtrace. To get a backtrace, at the (gdb) prompt, type in <c>bt</c>.
218     You will get something like this:
219     </p>
220    
221     <pre caption="Program backtrace">
222     (gdb) bt
223     #0 0xb7ec6dc0 in strcpy () from /lib/libc.so.6
224     #1 0x0804838c in run_it ()
225     #2 0x080483ba in main ()
226     </pre>
227    
228     <p>
229     So as we see here, first main() was run, then run_it(), and somewhere in run_it
230     lies the strcpy() at fault. Things such as this help developers narrow things
231     down. Now, there are a few exceptions to the output. First off is forgetting
232     to disable debug symbols with FEATURES="nostrip". With debug symbols stripped,
233     output looks something like this:
234     </p>
235    
236     <pre caption="Program backtrace With debug symbols stripped">
237     (gdb) bt
238     #0 0xb7e2cdc0 in strcpy () from /lib/libc.so.6
239     #1 0x0804838c in ?? ()
240     #2 0xbfd19510 in ?? ()
241     #3 0x00000000 in ?? ()
242     #4 0x00000000 in ?? ()
243     #5 0xb7eef148 in libgcc_s_personality () from /lib/libc.so.6
244     #6 0x080482ed in ?? ()
245     #7 0x080495b0 in ?? ()
246     #8 0xbfd19528 in ?? ()
247     #9 0xb7dd73b8 in __guard_setup () from /lib/libc.so.6
248     #10 0xb7dd742d in __guard_setup () from /lib/libc.so.6
249     #11 0x00000006 in ?? ()
250     #12 0xbfd19548 in ?? ()
251     #13 0x080483ba in ?? ()
252     #14 0x00000000 in ?? ()
253     #15 0x00000000 in ?? ()
254     #16 0xb7deebcc in __new_exitfn () from /lib/libc.so.6
255     #17 0x00000000 in ?? ()
256     #18 0xbfd19560 in ?? ()
257     #19 0xb7ef017c in nullserv () from /lib/libc.so.6
258     #20 0xb7dd6f37 in __libc_start_main () from /lib/libc.so.6
259     #21 0x00000001 in ?? ()
260     #22 0xbfd195d4 in ?? ()
261     #23 0xbfd195dc in ?? ()
262     #24 0x08048201 in ?? ()
263     </pre>
264    
265     <p>
266     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
268     crucial that debug symbols are <e>not</e> stripped. Now remember a while ago I
269     told you about the -g flag. Let's see what the output looks like with that:
270     </p>
271    
272     <pre caption="Program backtrace with -g flag">
273     (gdb) bt
274     #0 0xb7e4bdc0 in strcpy () from /lib/libc.so.6
275     #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
277     </pre>
278    
279     <p>
280     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
282     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.
284     </p>
285    
286     <pre caption="Filesize differences With -g flag">
287     <comment>(debug symbols stripped)</comment>
288     -rwxr-xr-x 1 chris users 3140 6/28 13:11 bad_code
289     <comment>(debug symbols enabled)</comment>
290     -rwxr-xr-x 1 chris users 6374 6/28 13:10 bad_code
291     <comment>(-g flag enabled)</comment>
292     -rwxr-xr-x 1 chris users 7366 6/28 13:11 bad_code
293     </pre>
294    
295     <p>
296     As you can see, -g adds about a 1000 more bytes to the file size over the one
297     with debugging symbols. However, as shown above, this increase in file size can
298     be worth it if presenting debug information to developers. Now that we have
299     obtained the backtrace, we can save it to a file by copying and pasting from the
300     terminal (if it's a non-x based terminal, you can use gpm. To keep this doc
301     simple, I recommend you read up on the documentation for gpm to see how to copy
302     and paste with it). Now that we're done with <c>gdb</c>, we can quit.
303     </p>
304    
305     <pre caption="Quitting GDB">
306     (gdb) quit
307     The program is running. Exit anyway? (y or n) y
308     $
309     </pre>
310    
311     <p>
312     This ends the walk-through of <c>gdb</c>. Using <c>gdb</c>, I hope that you will
313     be able to use it to create better bug reports. However, there are other types
314     of errors that can cause a program to fail during run time. One of the other
315     ways is through improper file access. We can find those using a nifty little
316     tool called <c>strace</c>.
317     </p>
318    
319     </body>
320     </section>
321     </chapter>
322    
323     <chapter>
324     <title>Finding file access errors using strace</title>
325     <section>
326     <title>Introduction</title>
327     <body>
328    
329     <p>
330     Programs often use files to get configuration information, get access
331     to hardware, or write logs. Often a program attempts to reach such files
332     incorrectly. A program called <c>strace</c> was created to help deal with
333     this. <c>strace</c> traces system calls (hence the name) which include
334     calls that use the memory and files. For our example, we're going to take a
335     program foobar2. This is an updated version of foobar. However, during the
336     changeover to foobar2, you notice all your configurations are missing! In
337     foobar version 1, you had it setup to say "foo", but now it's using the default
338     "bar".
339     </p>
340    
341     <pre caption="Foobar2 With an invalid configuration">
342     $ <i>./foobar2</i>
343     Configuration says: bar
344     </pre>
345    
346     <p>
347     Our previous configuration specifically had it set to foo, so let's use
348     <c>strace</c> to find out what's going on.
349     </p>
350    
351     </body>
352     </section>
353     <section>
354     <title>Using strace to track the issue</title>
355     <body>
356    
357     <p>
358     Let's have <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:
360     </p>
361    
362     <pre caption="Running foobar2 through strace">
363     # <i>strace -ostrace.log ./foobar2</i>
364     </pre>
365    
366     <p>
367 fox2mike 1.2 This creates a file called <path>strace.log</path> in the current directory. We
368     check the file, and shown below are the relevant parts from the file.
369 fox2mike 1.1 </p>
370    
371     <pre caption="A Look At the strace Log">
372     open(".foobar2/config", O_RDONLY) = 3
373     read(3, "bar", 3) = 3
374     </pre>
375    
376     <p>
377     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
379     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
381 fox2mike 1.2 config file from <path>.foobar</path> and modify it to produce the correct
382     results.
383 fox2mike 1.1 </p>
384    
385     </body>
386     </section>
387     <section>
388     <title>Conclusion</title>
389     <body>
390    
391     <p>
392     Now we've taken care of finding run time bugs. These bugs prove to be
393     problematic when you try and run your programs. However, run time errors are
394     the least of your concern if your program won't compile at all. Let's take a
395     look at how to address <c>emerge</c> compile errors.
396     </p>
397    
398     </body>
399     </section>
400     </chapter>
401    
402     <chapter>
403     <title>Handling emerge Errors</title>
404     <section>
405     <title>Introduction</title>
406     <body>
407    
408     <p>
409     <c>emerge</c> errors, such as the one displayed earlier, can be a major cause
410     of frustration for users. Reporting them is considered crucial for helping
411     maintain the health of Gentoo. Let's take a look at a sample ebuild, foobar2,
412     which contains some build errors.
413     </p>
414    
415     </body>
416     </section>
417     <section id="emerge_error">
418     <title>Evaluating emerge Errors</title>
419     <body>
420    
421     <p>
422     Let's take a look at this very simple <c>emerge</c> error:
423     </p>
424    
425     <pre caption="emerge Error">
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-7.o foobar2-7.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-8.o foobar2-8.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-9.o foobar2-9.c
429     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
430     foobar2.c:1:17: ogg.h: No such file or directory
431     make: *** [foobar2.o] Error 1
432    
433     !!! ERROR: sys-apps/foobar2-1.0 failed.
434     !!! Function src_compile, Line 19, Exitcode 2
435     !!! Make failed!
436     !!! If you need support, post the topmost build error, NOT this status message
437     </pre>
438    
439     <p>
440     The compile is going smoothly, then it stops and presents an error message. This
441     particular error can be split into 3 different sections, The compile, the build
442     error, and the emerge error message as shown below.
443     </p>
444    
445     <pre caption="Parts of the error">
446     <comment>(Compile Error)</comment>
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-7.o foobar2-7.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-8.o foobar2-8.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-9.o foobar2-9.c
450     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
451    
452     <comment>(Build Error)</comment>
453     foobar2.c:1:17: ogg.h: No such file or directory
454     make: *** [foobar2.o] Error 1
455    
456     <comment>(Emerge Error)</comment>
457     !!! ERROR: sys-apps/foobar2-1.0 failed.
458     !!! Function src_compile, Line 19, Exitcode 2
459     !!! Make failed!
460     !!! If you need support, post the topmost build error, NOT this status message
461     </pre>
462    
463     <p>
464     The compile is what leads up to the error. Most often, it's good to at least
465     include 10 lines of compile information so that the developer knows where the
466     compile is at. Make errors are the actual error, and the information the
467     developer needs. When you see "make: ***", this is often where the error has
468     occurred. Normally, you can copy and paste 10 lines above it and the developer
469     will be able to address the issue. However, this may not always work and we'll
470     take a look at an alternative shortly. The emerge error is what <c>emerge</c>
471     can address from the make error. Often people make the mistake of posting the
472     emerge error and that's all. This is useless by itself, but with make error and
473     compile information, a developer can get what application and what version of
474     the package is failing. As a side note, make is commonly used as the build
475     process for programs (<b>but not always</b>). If you can't find a "make: ***"
476     error anywhere, then simply copy and paste 20 lines before the emerge error.
477     This should take care of most all build system error messages. Now let's say the
478     errors seem to be quite large. 10 lines won't be enough to catch everything.
479     That's where PORT_LOGDIR comes into play.
480     </p>
481    
482     </body>
483     </section>
484     <section>
485     <title>emerge and PORT_LOGDIR</title>
486     <body>
487    
488     <p>
489     PORT_LOGDIR is a portage variable that sets up a log directory for separate
490     emerge logs. Let's take a look and see what that entails. First, run your emerge
491     with PORT_LOGDIR set to your favorite log location. Let's say we have a
492     location /var/log/portage. We'll use that for our log directory:
493     </p>
494    
495     <note>
496     In the default setup, /var/log/portage does not exist, and you will most likely
497     have to create it. If you do not, portage will fail to write the logs.
498     </note>
499    
500     <pre caption="emerge-ing With PORT_LOGDIR">
501     # <i>PORT_LOGDIR=/var/log/portage emerge foobar2</i>
502     </pre>
503    
504     <p>
505     Now the emerge fails again. However, this time we have a log we can work with,
506     and attach to the bug later on. Let's take a quick look at our log directory.
507     </p>
508    
509     <pre caption="PORT_LOGDIR Contents">
510     # <i>ls -la /var/log/portage</i>
511     total 16
512     drwxrws--- 2 root root 4096 Jun 30 10:08 .
513     drwxr-xr-x 15 root root 4096 Jun 30 10:08 ..
514     -rw-r--r-- 1 root root 7390 Jun 30 10:09 2115-foobar2-1.0.log
515     </pre>
516    
517     <p>
518     The log files have the format [counter]-[package name]-[version].log. Counter
519     is a special variable that is meant to state this package as the n-th package
520     you've emerged. This prevents duplicate logs from appearing. A quick look at
521     the log file will show the entire emerge process. This can be attached later
522     on as we'll see in the bug reporting section. Now that we've safely obtained
523     our information needed to report the bug we can continue to do so. However,
524     before we get started on that, we need to make sure no one else has reported
525     the issue. Let's take a look at searching for bugs.
526     </p>
527    
528     </body>
529     </section>
530     </chapter>
531    
532     <chapter>
533     <title>Searching Using Bugzilla</title>
534     <section>
535     <title>Introduction</title>
536     <body>
537    
538     <p>
539     <uri link="http://www.bugzilla.org">Bugzilla</uri> is what we at Gentoo use to
540     handle bugs. Gentoo's Bugzilla is reachable by HTTPS and HTTP. HTTPS is
541     available for those on insecure networks or simply paranoid :). For the sake of
542     consistency, I will be using the HTTPS version in the examples to follow. Head
543     over to <uri link="https://bugs.gentoo.org">Gentoo Bugs</uri> to see how it
544     looks.
545     </p>
546    
547     <p>
548     One of the most frustrating thing for developers and bug-wranglers is finding
549     duplicate bug reports. This causes them valuable time they could be using to
550     find new and more important bugs. Often, this can be prevented by a few simple
551     search methods. So we're going to see how to search for bugs and find out if
552     you have one that's similar. For this example, we're going to use the xclass
553     emerge error that was used earlier:
554     </p>
555    
556     <pre caption="xclass emerge error">
557     /usr/lib/gcc-lib/i686-pc-linux-gnu/3.3.2/include/g++-v3/backward/backward_warning.h:32:2:
558     warning: #warning This file includes at least one deprecated or antiquated
559     header. Please consider using one of the 32 headers found in section 17.4.1.2 of
560     the C++ standard. Examples include substituting the &lt;X&gt; header for the &lt;X.h&gt;
561     header for C++ includes, or &lt;sstream&gt; instead of the deprecated header
562     &lt;strstream.h&gt;. To disable this warning use -Wno-deprecated.
563     In file included from main.cc:40:
564     menudef.h:55: error: brace-enclosed initializer used to initialize `
565     OXPopupMenu*'
566     menudef.h:62: error: brace-enclosed initializer used to initialize `
567     OXPopupMenu*'
568     menudef.h:70: error: brace-enclosed initializer used to initialize `
569     OXPopupMenu*'
570     menudef.h:78: error: brace-enclosed initializer used to initialize `
571     OXPopupMenu*'
572     main.cc: In member function `void OXMain::DoOpen()':
573     main.cc:323: warning: unused variable `FILE*fp'
574     main.cc: In member function `void OXMain::DoSave(char*)':
575     main.cc:337: warning: unused variable `FILE*fp'
576     make[1]: *** [main.o] Error 1
577     make[1]: Leaving directory
578     `/var/tmp/portage/xclass-0.7.4/work/xclass-0.7.4/example-app'
579     make: *** [shared] Error 2
580    
581     !!! ERROR: x11-libs/xclass-0.7.4 failed.
582     !!! Function src_compile, Line 29, Exitcode 2
583     !!! 'emake shared' failed
584     </pre>
585    
586     <p>
587     So to begin searching, we head over to the <uri
588 fox2mike 1.2 link="https://bugs.gentoo.org/">Bugzilla Homepage</uri>.
589 fox2mike 1.1 </p>
590    
591     <figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/>
592    
593     <p>
594     In order to begin our search, we'll click on "Query Existing bug reports". The
595     reason why we choose this versus the basic bug search is because the basic bug
596     search tends to give vague results and often hinders users from looking
597     through the results and finding the duplicate bug. Once we click on the query
598     screen, we reach the next page:
599     </p>
600    
601     <figure link="/images/docs/bugzie-search.png" caption="Bugzilla Search Page"/>
602    
603     <note>
604     If you've used the Advanced Search before, you'll most likely see that screen
605     instead.
606     </note>
607    
608     <p>
609     Proceed on clicking the "Advanced Search" link to bring up the Advanced
610     Search page:
611     </p>
612    
613     <figure link="/images/docs/bugzie-adv-search.png" caption="Advanced Search Page"/>
614    
615     <p>
616     This is how the Advanced Search Page looks like. While it may seem overwhelming
617     at first, we're going to look at a few simple areas to narrow down the rather
618     vague searches bugzilla returns.
619     </p>
620    
621     <figure link="/images/docs/bugzie-content.png" caption="Content"/>
622    
623     <p>
624     The first field is the summary of the bug. Here we're simply going to put the
625     name of the package that's crashing. If you still don't get results, try
626     removing the package name, just in case someone didn't put that in the summary
627     (highly unlikely, but I've seen my fair share of strange bug reports).
628     </p>
629    
630     <p>
631     Product, Component, and Version should all be set to the default. This
632     prevents us from being too specific and missing all the bugs.
633     </p>
634    
635     <p>
636     Comment is the important part. Use comment to list what appears to be a
637     specific instance of the error. Basically, don't use anything like the
638     beginning of the build error, find a line that's before it stating a true
639     error. Also, you'll want to filter out any punctuation to prevent bugzilla
640     from interpreting the results the comment the wrong way. Example from the xclass
641     emerge error:
642     </p>
643    
644     <pre caption="Comment Line Content">
645     menudef.h:78: error: brace-enclosed initializer used to initialize `OXPopupMenu'
646     <comment>(Remove the quotes ' ')</comment>
647     menudef.h 78 error brace-enclosed initializer used to initialize OXPopupMenu
648     </pre>
649    
650     <p>
651     The above is specific enough to where we'll find the bug without wading through
652     other xclass compile failure candidates.
653     </p>
654    
655     <p>
656     URI, Whiteboard, and Keywords can all be left alone. What we've entered so far
657     should be enough to find our bug. Let's see what we have filled out:
658     </p>
659    
660     <figure link="/images/docs/bugzie-comp-search.png" caption="Completed Search Form"/>
661    
662     <p>
663     Now we click on the Search button and here come the results:
664     </p>
665    
666     <figure link="/images/docs/bugzie-search-result.png" caption="Search Results"/>
667    
668     <p>
669     Only 2 bugs! That's a lot easier to deal with. We click on the first one to
670     check, and sure enough it's the one we're looking for:
671     </p>
672    
673     <figure link="/images/docs/bugzie-located.png" caption="Bug Located"/>
674    
675     <p>
676     Not only is it the one we want, but it has also been resolved. By checking the
677     last comment we see the solution and know what to do in order to resolve it.
678     Now, let's see what would have happened if we had not used the advanced search:
679     </p>
680    
681     <figure link="/images/docs/bugzie-basic-search-result.png" caption="Basic Search Results"/>
682    
683     <p>
684     4 more bugs to deal with! It gets even worse with larger packages. However,
685     with these simple tools, we're able to significantly narrow down the search to
686     try and locate a specific bug.
687     </p>
688    
689     </body>
690     </section>
691     <section>
692     <title>Conclusion</title>
693     <body>
694    
695     <p>
696     Let's say that you have searched and searched but still can't find a bug.
697     You've found yourself a new bug. Let's take a look at the bug reporting process
698     for submitting your new bug.
699     </p>
700    
701     </body>
702     </section>
703     </chapter>
704    
705     <chapter>
706     <title>Reporting Bugs</title>
707     <section>
708     <title>Introduction</title>
709     <body>
710    
711     <p>
712     In this chapter, we'll figure out how to use Bugzilla to file a shiny, new bug.
713     Head over to <uri link="https://bugs.gentoo.org">Gentoo Bugs</uri> and...
714     </p>
715    
716     <figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/>
717    
718     <p>
719     Go ahead and click on "Report a Bug - Using the Guided format".
720     </p>
721    
722     <figure link="/images/docs/bugzie-prod-select.png" caption="Product Selection"/>
723    
724     <p>
725     As you can see, <b>major</b> emphasis has been placed on putting your bug in the
726     right place. Gentoo Linux is where a large majority of bugs go. Despite this,
727     some people will file ebuild bugs in portage development (assumption that
728     portage team handles the portage tree) or infra (assumption that infra has
729     access to mirrors and rsync and can fix it directly). This is simply not how
730     things work. Our bug goes in Gentoo Linux, as it's an ebuild bug. We head over
731     there and are presented with the multi-step bug reporting process.
732     </p>
733    
734     <note>
735     We would rather see a non-Gentoo Linux bug filed in Gentoo Linux than a Gentoo
736     Linux bug filed in non-Gentoo Linux projects! While neither is preferred, the
737     former is more acceptable and understandable (except website bugs.. we might
738     have an issue with that...)
739     </note>
740    
741     <p>
742     Let us now proceed with Step 1...
743     </p>
744    
745     <figure link="/images/docs/bugzie-guide-step1.png" caption="Guided Format Step 1"/>
746    
747     <p>
748     The first step here is really important (as the red text tells you). This is
749     where you search to see that someone else hasn't hit the same bug you have, yet.
750     If you do skip this step, and a bug like yours already exists, it will be marked
751     as a DUPLICATE thus wasting a large amount of QA effort. To give you an idea,
752     the numbers that are struck out above are duplicate bugs. Now comes step 2,
753     where we give the information.
754     </p>
755    
756     </body>
757     </section>
758     <section>
759     <title>Required Information</title>
760     <body>
761    
762     <p>
763     Onto Step 2, let's see what we have here.
764     </p>
765    
766     <figure link="/images/docs/bugzie-basic.png" caption="Basic Information"/>
767    
768     <p>
769     First, there's the product. This is Gentoo Linux, which we selected earlier.
770     Component is where the problem occurs. We use this to help us sort out the
771     severity of the issue (i.e. baselayout and core systems will be more important
772     than new ebuilds or application bugs). Here we select Application, as it is an
773     application at fault. Hardware platform is what architecture you're running.
774     If you were running SPARC, you would set it to SPARC. For this example, we know
775     this error can occur on multiple architectures, so we'll select All. Operating
776     System is what Operating System you're using. Because Gentoo is considered a
777     "Meta-distribution", it can run on other operating systems beside Linux.
778     Examples are Gentoo on MacOS, Gentoo on FreeBSD, etc. For this example,
779     we'll select All, as this can occur on all types of systems. Build Identifier
780     is what is being used to report the bugs (for logging purposes). You can just
781     leave this as is. Let's see what we have so far:
782     </p>
783    
784     <figure link="/images/docs/bugzie-basic-comp.png" caption="Completed Basic Information"/>
785    
786     <p>
787     That does look good, so we'll begin with the actual report. In this instance,
788     we'll use the foobar2 bug as our example. URL is used to point to errors on a
789     site someplace (pastebin, etc.). However, doing it inside the bug allows the
790     developers be able to reference to it at any time and is preferred. Then we have
791     the summary. In the summary, you should put the package category, name, and
792     number. Not including the category really isn't too bad, but it's recommended.
793     If you don't include the package name, however, we won't know what you're
794     filling a bug for, and will have to ask you about it later. The version number
795     is important for people searching for bugs. If 20 people filed bugs and not one
796     put a version number, how would people looking for similar bugs be able to tell
797     if one was there's? They'd have to look through every single bug, which isn't
798     too hard, but if there are say, 200 bugs.. it's not that easy. After all the
799     package information, you'll want to include a small description of the incident.
800     Here's an example:
801     </p>
802    
803     <figure link="/images/docs/bugzie-summary.png" caption="Summary"/>
804    
805     <p>
806     Just these simple rules can make handling bugs a lot easier. Next are the
807     details. Here we put in the information about the bug. We'll demonstrate with an
808     example:
809     </p>
810    
811     <figure link="/images/docs/bugzie-details.png" caption="Details"/>
812    
813     <p>
814     So now the developer knows why we're filing the bug. They can then try to
815     reproduce it. Reproducibility tells us how often we were able to make the
816     problem recur. In this example, we can reproduce it any time simply by running
817     foobar2. Let's put that information in:
818     </p>
819    
820     <figure link="/images/docs/bugzie-reprod.png" caption="Reproduction"/>
821    
822     <p>
823     So now we have explained how we found the bug. Next we want to explain what
824     the results were and what we think they should be:
825     </p>
826    
827     <figure link="/images/docs/bugzie-results.png" caption="Results"/>
828    
829     <p>
830     Next we put additional information. This can be things such as stack traces,
831     <b>sections</b> of strace logs, but most importantly, your emerge --info output.
832     Here's an example:
833     </p>
834    
835     <figure link="/images/docs/bugzie-addl-info.png" caption="Additional Information"/>
836    
837     <p>
838     Lastly we select the severity of the bug. Please look this over carefully. In
839     most cases it's OK to leave it as is and someone will raise/lower it for you.
840     However, if you raise the severity of the bug, please make sure you read it over
841     carefully and make sure you're not making a mistake. Here we will set it to the
842     default of normal:
843     </p>
844    
845     <figure link="/images/docs/bugzie-sev.png" caption="Severity"/>
846    
847     <p>
848     Now we can submit the bug report by clicking on the Submit Bug Report box. You
849     will now see your new bug come up. See <uri
850     link="https://bugs.gentoo.org/show_bug.cgi?id=97265">Bug 97561</uri> for what
851     the result looks like. We've reported our bug! Now let's see how it's dealt
852     with.
853     </p>
854    
855     </body>
856     </section>
857     </chapter>
858    
859     <chapter>
860     <title>Working With Your Bug</title>
861     <section>
862     <body>
863    
864     <p>
865     looking at the bug, we see the information we provided earlier:
866     </p>
867    
868     <figure link="/images/docs/bugzie-new-basic.png" caption="New Bug Basic Information"/>
869    
870     <p>
871     And our details are there too:
872     </p>
873    
874     <figure link="/images/docs/bugzie-new-details.png" caption="New Bug Details"/>
875    
876     <p>
877     Now as you can see, the bug has been assigned to bug-wranglers@gentoo.org. This
878     is the default location for Application component bugs. However, bug-wranglers
879     (usually) won't fix our bugs, so we'll reassign it to someone that can (you can
880     let bug-wranglers re-assign it for you as well). For this we use the package's
881     metadata.xml. You can normally find them in
882     /usr/portage/category/package/metadata.xml. Here's one I've made up for foobar2:
883     </p>
884    
885     <pre caption="metadata.xml">
886     &lt;?xml version="1.0" encoding="UTF-8"?&gt;
887     &lt;!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"&gt;
888     &lt;pkgmetadata&gt;
889     &lt;herd&gt;chriswhite&lt;/herd&gt;
890     &lt;maintainer&gt;
891     &lt;email&gt;chriswhite@gentoo.org&lt;/email&gt;
892     &lt;name&gt;Chris White&lt;/name&gt;
893     &lt;/maintainer&gt;
894     &lt;longdescription lang="en"&gt;
895     Foobar2 is a package that uses a configuration file to display a word.
896     &lt;/longdescription&gt;
897     &lt;/pkgmetadata&gt;
898     </pre>
899    
900     <p>
901     Notice the maintainer section.T his lists the maintainer of the package, which
902     in this case is myself, Chris White. The email listed is chriswhite@gentoo.org.
903     We will use this to re-assign the bug to the proper person. To do this, click
904     the bubble next to Reassign bug to, then fill in the email:
905     </p>
906    
907     <note>
908     A package without a metadata.xml file should be re-assigned to
909     maintainer-needed@gentoo.org.
910     </note>
911    
912     <figure link="/images/docs/bugzie-reassign.png" caption="Bug Reassignment"/>
913    
914     <p>
915     Then hit the Commit button for the changes to take place. The bug has been
916     reassigned to me. Shortly afterward, you notice (by email usually) that I've
917     responded to your bug. I've stated that I'd like to see an strace log to figure
918     out how the program is trying to reach your configuration file. You follow the
919     previous instructions on using strace and obtain an strace log. Now you need to
920     attach it to the bug. In order to do this, click on "Create A New Attachment".
921     </p>
922    
923     <figure link="/images/docs/bugzie-new-attach.png" caption="New Attachment"/>
924    
925     <p>
926     Now we have to attach the log. We click on the "Browse..." button under "File"
927     and select the strace log. For Description, we'll put "strace log". Content-Type
928     is what kind of file we're attaching. A common mistake is to set it to
929     auto. In most cases it's best to manually set it. Our log file is a
930     plain text file, so we select "plain text (text/plain)". Obsoletes are for when
931     you are attaching a revision to a previously attached file. You can simply click
932     a check box next to the old file and Bugzilla will cross it out in the bug,
933     indicating that the attachment has been obsoleted. Reassignment means you want
934     to take the bug yourself. I rarely tend to use this.. and I don't think you will
935     need to at some point (unless you create great patches and we don't care about
936     you taking our bugs ;). Comments are for leaving comments about the file you're
937     posting. We'll put "Here is the strace file you requested". Now we have
938     something like this:
939     </p>
940    
941     <figure link="/images/docs/bugzie-new-attach-comp.png" caption="New Attachment Completed"/>
942    
943     <p>
944     We Submit the patch and it is now reflected on the bug report.
945     </p>
946    
947     <figure link="/images/docs/bugzie-strace.png" caption="Attached strace log"/>
948    
949     <p>
950     Now, while we're waiting another person notices your bug during step 1 of the
951     Guided Format. This person wants to see the status of the bug as well. He or
952     she may do so by putting their email in the Add CC field like so:
953     </p>
954    
955     <figure link="/images/docs/bugzie-add-email.png" caption="Adding Email To CC:"/>
956    
957     <note>
958     Email addresses must be registered with bugzilla. In order to CC multiple
959     addresses, simply separate them with commas or spaces.
960     </note>
961    
962     <p>
963     After all this work, the bug can undergo various status markings. Here's a few:
964     </p>
965    
966     <ul>
967     <li>
968 fox2mike 1.2 UNCONFIRMED - You're generally not going to see this too often. This
969 fox2mike 1.1 means that a bug reporter has opened a bug using the advanced method and is
970     uncertain his or her bug is an actual bug.
971 fox2mike 1.2 </li>
972 fox2mike 1.1 <li>
973 fox2mike 1.2 NEW - Bugs that are first opened are considered new.
974     </li>
975 fox2mike 1.1 <li>
976 fox2mike 1.2 ASSIGNED - When the person you've assigned the bug too validates your
977 fox2mike 1.1 bug, it will often receive ASSIGNED status while they figure out the issue.
978     This let's you know that they've accepted your bug as a real bug.
979 fox2mike 1.2 </li>
980 fox2mike 1.1 <li>
981 fox2mike 1.2 REOPENED - Someone has resolved a bug and you think the solution is not
982 fox2mike 1.1 feasible or the problem still persists. At this point, you may re-open the
983     bug. However <b>please do not abuse this</b>. If a developer closes the bug a
984     second or even third time, chances are that your bug is closed.
985 fox2mike 1.2 </li>
986 fox2mike 1.1 </ul>
987    
988     <p>
989     Now shortly afterward, I find the error in the strace log. I resolve the bug
990     as RESOLVED FIXED and say that there was a change in the location of
991     configuration files, and that I will update the ebuild with a warning about it.
992     The bug now becomes resolved, and you are displayed with this:
993     </p>
994    
995     <figure link="/images/docs/bugzie-reso.png" caption="Resolved Bug"/>
996    
997     <p>
998     Also note the section here:
999     </p>
1000    
1001     <figure link="/images/docs/bugzie-options.png" caption="Bug Options"/>
1002    
1003     <p>
1004     This gives you the option of Reopening the bug if you wish to (i.e. the developer
1005     thinks it's resolved but it's really not to your standards). Now our bug is
1006     fixed! However, different resolutions can occur. Here's a small list:
1007     </p>
1008    
1009     <ul>
1010     <li>
1011 fox2mike 1.2 FIXED - The bug is fixed, follow the instructions to resolve your
1012 fox2mike 1.1 issue.
1013 fox2mike 1.2 </li>
1014 fox2mike 1.1 <li>
1015 fox2mike 1.2 INVALID - You did not do something specifically documented, causing the
1016 fox2mike 1.1 bug
1017 fox2mike 1.2 </li>
1018 fox2mike 1.1 <li>
1019 fox2mike 1.2 DUPLICATE - You didn't use this guide and reported a duplicate bug
1020 fox2mike 1.1 :)
1021 fox2mike 1.2 </li>
1022 fox2mike 1.1 <li>
1023 fox2mike 1.2 WORKSFORME - Developer/person assigned the bug cannot reproduce your
1024 fox2mike 1.1 error
1025 fox2mike 1.2 </li>
1026 fox2mike 1.1 </ul>
1027    
1028     </body>
1029     </section>
1030    
1031     <section>
1032     <title>Conclusion</title>
1033     <body>
1034    
1035     <p>
1036     This concludes the howto on working with Bugzilla. I hope you find this useful.
1037     If you have any questions, comments, or ideas regarding this document, please
1038     send them to me at <mail
1039     link="chriswhite@gentoo.org">chriswhite@gentoo.org</mail>. Special
1040     thanks go to moreon for his notes on -g flags and compile errors, the people at
1041     #gentoo-bugs for helping out with bug-wrangling, and Griffon26 for his notes on
1042     maintainer-needed.
1043     </p>
1044    
1045     </body>
1046     </section>
1047     </chapter>
1048     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20