/[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.1 - (show annotations) (download) (as text)
Thu Jul 7 12:02:21 2005 UTC (9 years ago) by fox2mike
Branch: MAIN
File MIME type: application/xml
#97274 - Initial version of the doc, Lots of thanks to Chris "Da PUNK" White :)

1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/bugzilla-howto.xml,v 1.7 2005/07/07 11:56:02 swift Exp $ -->
4
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 <version>1.0</version>
24 <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 This creates a file called strace.log in the current directory. We check the
368 file, and shown below are the relevant parts from the file.
369 </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 config file from .foobar and modify it to produce the correct results.
382 </p>
383
384 </body>
385 </section>
386 <section>
387 <title>Conclusion</title>
388 <body>
389
390 <p>
391 Now we've taken care of finding run time bugs. These bugs prove to be
392 problematic when you try and run your programs. However, run time errors are
393 the least of your concern if your program won't compile at all. Let's take a
394 look at how to address <c>emerge</c> compile errors.
395 </p>
396
397 </body>
398 </section>
399 </chapter>
400
401 <chapter>
402 <title>Handling emerge Errors</title>
403 <section>
404 <title>Introduction</title>
405 <body>
406
407 <p>
408 <c>emerge</c> errors, such as the one displayed earlier, can be a major cause
409 of frustration for users. Reporting them is considered crucial for helping
410 maintain the health of Gentoo. Let's take a look at a sample ebuild, foobar2,
411 which contains some build errors.
412 </p>
413
414 </body>
415 </section>
416 <section id="emerge_error">
417 <title>Evaluating emerge Errors</title>
418 <body>
419
420 <p>
421 Let's take a look at this very simple <c>emerge</c> error:
422 </p>
423
424 <pre caption="emerge Error">
425 gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2-7.o foobar2-7.c
426 gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2-8.o foobar2-8.c
427 gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2-9.o foobar2-9.c
428 gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2.o foobar2.c
429 foobar2.c:1:17: ogg.h: No such file or directory
430 make: *** [foobar2.o] Error 1
431
432 !!! ERROR: sys-apps/foobar2-1.0 failed.
433 !!! Function src_compile, Line 19, Exitcode 2
434 !!! Make failed!
435 !!! If you need support, post the topmost build error, NOT this status message
436 </pre>
437
438 <p>
439 The compile is going smoothly, then it stops and presents an error message. This
440 particular error can be split into 3 different sections, The compile, the build
441 error, and the emerge error message as shown below.
442 </p>
443
444 <pre caption="Parts of the error">
445 <comment>(Compile Error)</comment>
446 gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2-7.o foobar2-7.c
447 gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2-8.o foobar2-8.c
448 gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2-9.o foobar2-9.c
449 gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2.o foobar2.c
450
451 <comment>(Build Error)</comment>
452 foobar2.c:1:17: ogg.h: No such file or directory
453 make: *** [foobar2.o] Error 1
454
455 <comment>(Emerge Error)</comment>
456 !!! ERROR: sys-apps/foobar2-1.0 failed.
457 !!! Function src_compile, Line 19, Exitcode 2
458 !!! Make failed!
459 !!! If you need support, post the topmost build error, NOT this status message
460 </pre>
461
462 <p>
463 The compile is what leads up to the error. Most often, it's good to at least
464 include 10 lines of compile information so that the developer knows where the
465 compile is at. Make errors are the actual error, and the information the
466 developer needs. When you see "make: ***", this is often where the error has
467 occurred. Normally, you can copy and paste 10 lines above it and the developer
468 will be able to address the issue. However, this may not always work and we'll
469 take a look at an alternative shortly. The emerge error is what <c>emerge</c>
470 can address from the make error. Often people make the mistake of posting the
471 emerge error and that's all. This is useless by itself, but with make error and
472 compile information, a developer can get what application and what version of
473 the package is failing. As a side note, make is commonly used as the build
474 process for programs (<b>but not always</b>). If you can't find a "make: ***"
475 error anywhere, then simply copy and paste 20 lines before the emerge error.
476 This should take care of most all build system error messages. Now let's say the
477 errors seem to be quite large. 10 lines won't be enough to catch everything.
478 That's where PORT_LOGDIR comes into play.
479 </p>
480
481 </body>
482 </section>
483 <section>
484 <title>emerge and PORT_LOGDIR</title>
485 <body>
486
487 <p>
488 PORT_LOGDIR is a portage variable that sets up a log directory for separate
489 emerge logs. Let's take a look and see what that entails. First, run your emerge
490 with PORT_LOGDIR set to your favorite log location. Let's say we have a
491 location /var/log/portage. We'll use that for our log directory:
492 </p>
493
494 <note>
495 In the default setup, /var/log/portage does not exist, and you will most likely
496 have to create it. If you do not, portage will fail to write the logs.
497 </note>
498
499 <pre caption="emerge-ing With PORT_LOGDIR">
500 # <i>PORT_LOGDIR=/var/log/portage emerge foobar2</i>
501 </pre>
502
503 <p>
504 Now the emerge fails again. However, this time we have a log we can work with,
505 and attach to the bug later on. Let's take a quick look at our log directory.
506 </p>
507
508 <pre caption="PORT_LOGDIR Contents">
509 # <i>ls -la /var/log/portage</i>
510 total 16
511 drwxrws--- 2 root root 4096 Jun 30 10:08 .
512 drwxr-xr-x 15 root root 4096 Jun 30 10:08 ..
513 -rw-r--r-- 1 root root 7390 Jun 30 10:09 2115-foobar2-1.0.log
514 </pre>
515
516 <p>
517 The log files have the format [counter]-[package name]-[version].log. Counter
518 is a special variable that is meant to state this package as the n-th package
519 you've emerged. This prevents duplicate logs from appearing. A quick look at
520 the log file will show the entire emerge process. This can be attached later
521 on as we'll see in the bug reporting section. Now that we've safely obtained
522 our information needed to report the bug we can continue to do so. However,
523 before we get started on that, we need to make sure no one else has reported
524 the issue. Let's take a look at searching for bugs.
525 </p>
526
527 </body>
528 </section>
529 </chapter>
530
531 <chapter>
532 <title>Searching Using Bugzilla</title>
533 <section>
534 <title>Introduction</title>
535 <body>
536
537 <p>
538 <uri link="http://www.bugzilla.org">Bugzilla</uri> is what we at Gentoo use to
539 handle bugs. Gentoo's Bugzilla is reachable by HTTPS and HTTP. HTTPS is
540 available for those on insecure networks or simply paranoid :). For the sake of
541 consistency, I will be using the HTTPS version in the examples to follow. Head
542 over to <uri link="https://bugs.gentoo.org">Gentoo Bugs</uri> to see how it
543 looks.
544 </p>
545
546 <p>
547 One of the most frustrating thing for developers and bug-wranglers is finding
548 duplicate bug reports. This causes them valuable time they could be using to
549 find new and more important bugs. Often, this can be prevented by a few simple
550 search methods. So we're going to see how to search for bugs and find out if
551 you have one that's similar. For this example, we're going to use the xclass
552 emerge error that was used earlier:
553 </p>
554
555 <pre caption="xclass emerge error">
556 /usr/lib/gcc-lib/i686-pc-linux-gnu/3.3.2/include/g++-v3/backward/backward_warning.h:32:2:
557 warning: #warning This file includes at least one deprecated or antiquated
558 header. Please consider using one of the 32 headers found in section 17.4.1.2 of
559 the C++ standard. Examples include substituting the &lt;X&gt; header for the &lt;X.h&gt;
560 header for C++ includes, or &lt;sstream&gt; instead of the deprecated header
561 &lt;strstream.h&gt;. To disable this warning use -Wno-deprecated.
562 In file included from main.cc:40:
563 menudef.h:55: error: brace-enclosed initializer used to initialize `
564 OXPopupMenu*'
565 menudef.h:62: error: brace-enclosed initializer used to initialize `
566 OXPopupMenu*'
567 menudef.h:70: error: brace-enclosed initializer used to initialize `
568 OXPopupMenu*'
569 menudef.h:78: error: brace-enclosed initializer used to initialize `
570 OXPopupMenu*'
571 main.cc: In member function `void OXMain::DoOpen()':
572 main.cc:323: warning: unused variable `FILE*fp'
573 main.cc: In member function `void OXMain::DoSave(char*)':
574 main.cc:337: warning: unused variable `FILE*fp'
575 make[1]: *** [main.o] Error 1
576 make[1]: Leaving directory
577 `/var/tmp/portage/xclass-0.7.4/work/xclass-0.7.4/example-app'
578 make: *** [shared] Error 2
579
580 !!! ERROR: x11-libs/xclass-0.7.4 failed.
581 !!! Function src_compile, Line 29, Exitcode 2
582 !!! 'emake shared' failed
583 </pre>
584
585 <p>
586 So to begin searching, we head over to the <uri
587 link="http://bugs.gentoo.org/">Bugzilla Homepage</uri>.
588 </p>
589
590 <figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/>
591
592 <p>
593 In order to begin our search, we'll click on "Query Existing bug reports". The
594 reason why we choose this versus the basic bug search is because the basic bug
595 search tends to give vague results and often hinders users from looking
596 through the results and finding the duplicate bug. Once we click on the query
597 screen, we reach the next page:
598 </p>
599
600 <figure link="/images/docs/bugzie-search.png" caption="Bugzilla Search Page"/>
601
602 <note>
603 If you've used the Advanced Search before, you'll most likely see that screen
604 instead.
605 </note>
606
607 <p>
608 Proceed on clicking the "Advanced Search" link to bring up the Advanced
609 Search page:
610 </p>
611
612 <figure link="/images/docs/bugzie-adv-search.png" caption="Advanced Search Page"/>
613
614 <p>
615 This is how the Advanced Search Page looks like. While it may seem overwhelming
616 at first, we're going to look at a few simple areas to narrow down the rather
617 vague searches bugzilla returns.
618 </p>
619
620 <figure link="/images/docs/bugzie-content.png" caption="Content"/>
621
622 <p>
623 The first field is the summary of the bug. Here we're simply going to put the
624 name of the package that's crashing. If you still don't get results, try
625 removing the package name, just in case someone didn't put that in the summary
626 (highly unlikely, but I've seen my fair share of strange bug reports).
627 </p>
628
629 <p>
630 Product, Component, and Version should all be set to the default. This
631 prevents us from being too specific and missing all the bugs.
632 </p>
633
634 <p>
635 Comment is the important part. Use comment to list what appears to be a
636 specific instance of the error. Basically, don't use anything like the
637 beginning of the build error, find a line that's before it stating a true
638 error. Also, you'll want to filter out any punctuation to prevent bugzilla
639 from interpreting the results the comment the wrong way. Example from the xclass
640 emerge error:
641 </p>
642
643 <pre caption="Comment Line Content">
644 menudef.h:78: error: brace-enclosed initializer used to initialize `OXPopupMenu'
645 <comment>(Remove the quotes ' ')</comment>
646 menudef.h 78 error brace-enclosed initializer used to initialize OXPopupMenu
647 </pre>
648
649 <p>
650 The above is specific enough to where we'll find the bug without wading through
651 other xclass compile failure candidates.
652 </p>
653
654 <p>
655 URI, Whiteboard, and Keywords can all be left alone. What we've entered so far
656 should be enough to find our bug. Let's see what we have filled out:
657 </p>
658
659 <figure link="/images/docs/bugzie-comp-search.png" caption="Completed Search Form"/>
660
661 <p>
662 Now we click on the Search button and here come the results:
663 </p>
664
665 <figure link="/images/docs/bugzie-search-result.png" caption="Search Results"/>
666
667 <p>
668 Only 2 bugs! That's a lot easier to deal with. We click on the first one to
669 check, and sure enough it's the one we're looking for:
670 </p>
671
672 <figure link="/images/docs/bugzie-located.png" caption="Bug Located"/>
673
674 <p>
675 Not only is it the one we want, but it has also been resolved. By checking the
676 last comment we see the solution and know what to do in order to resolve it.
677 Now, let's see what would have happened if we had not used the advanced search:
678 </p>
679
680 <figure link="/images/docs/bugzie-basic-search-result.png" caption="Basic Search Results"/>
681
682 <p>
683 4 more bugs to deal with! It gets even worse with larger packages. However,
684 with these simple tools, we're able to significantly narrow down the search to
685 try and locate a specific bug.
686 </p>
687
688 </body>
689 </section>
690 <section>
691 <title>Conclusion</title>
692 <body>
693
694 <p>
695 Let's say that you have searched and searched but still can't find a bug.
696 You've found yourself a new bug. Let's take a look at the bug reporting process
697 for submitting your new bug.
698 </p>
699
700 </body>
701 </section>
702 </chapter>
703
704 <chapter>
705 <title>Reporting Bugs</title>
706 <section>
707 <title>Introduction</title>
708 <body>
709
710 <p>
711 In this chapter, we'll figure out how to use Bugzilla to file a shiny, new bug.
712 Head over to <uri link="https://bugs.gentoo.org">Gentoo Bugs</uri> and...
713 </p>
714
715 <figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/>
716
717 <p>
718 Go ahead and click on "Report a Bug - Using the Guided format".
719 </p>
720
721 <figure link="/images/docs/bugzie-prod-select.png" caption="Product Selection"/>
722
723 <p>
724 As you can see, <b>major</b> emphasis has been placed on putting your bug in the
725 right place. Gentoo Linux is where a large majority of bugs go. Despite this,
726 some people will file ebuild bugs in portage development (assumption that
727 portage team handles the portage tree) or infra (assumption that infra has
728 access to mirrors and rsync and can fix it directly). This is simply not how
729 things work. Our bug goes in Gentoo Linux, as it's an ebuild bug. We head over
730 there and are presented with the multi-step bug reporting process.
731 </p>
732
733 <note>
734 We would rather see a non-Gentoo Linux bug filed in Gentoo Linux than a Gentoo
735 Linux bug filed in non-Gentoo Linux projects! While neither is preferred, the
736 former is more acceptable and understandable (except website bugs.. we might
737 have an issue with that...)
738 </note>
739
740 <p>
741 Let us now proceed with Step 1...
742 </p>
743
744 <figure link="/images/docs/bugzie-guide-step1.png" caption="Guided Format Step 1"/>
745
746 <p>
747 The first step here is really important (as the red text tells you). This is
748 where you search to see that someone else hasn't hit the same bug you have, yet.
749 If you do skip this step, and a bug like yours already exists, it will be marked
750 as a DUPLICATE thus wasting a large amount of QA effort. To give you an idea,
751 the numbers that are struck out above are duplicate bugs. Now comes step 2,
752 where we give the information.
753 </p>
754
755 </body>
756 </section>
757 <section>
758 <title>Required Information</title>
759 <body>
760
761 <p>
762 Onto Step 2, let's see what we have here.
763 </p>
764
765 <figure link="/images/docs/bugzie-basic.png" caption="Basic Information"/>
766
767 <p>
768 First, there's the product. This is Gentoo Linux, which we selected earlier.
769 Component is where the problem occurs. We use this to help us sort out the
770 severity of the issue (i.e. baselayout and core systems will be more important
771 than new ebuilds or application bugs). Here we select Application, as it is an
772 application at fault. Hardware platform is what architecture you're running.
773 If you were running SPARC, you would set it to SPARC. For this example, we know
774 this error can occur on multiple architectures, so we'll select All. Operating
775 System is what Operating System you're using. Because Gentoo is considered a
776 "Meta-distribution", it can run on other operating systems beside Linux.
777 Examples are Gentoo on MacOS, Gentoo on FreeBSD, etc. For this example,
778 we'll select All, as this can occur on all types of systems. Build Identifier
779 is what is being used to report the bugs (for logging purposes). You can just
780 leave this as is. Let's see what we have so far:
781 </p>
782
783 <figure link="/images/docs/bugzie-basic-comp.png" caption="Completed Basic Information"/>
784
785 <p>
786 That does look good, so we'll begin with the actual report. In this instance,
787 we'll use the foobar2 bug as our example. URL is used to point to errors on a
788 site someplace (pastebin, etc.). However, doing it inside the bug allows the
789 developers be able to reference to it at any time and is preferred. Then we have
790 the summary. In the summary, you should put the package category, name, and
791 number. Not including the category really isn't too bad, but it's recommended.
792 If you don't include the package name, however, we won't know what you're
793 filling a bug for, and will have to ask you about it later. The version number
794 is important for people searching for bugs. If 20 people filed bugs and not one
795 put a version number, how would people looking for similar bugs be able to tell
796 if one was there's? They'd have to look through every single bug, which isn't
797 too hard, but if there are say, 200 bugs.. it's not that easy. After all the
798 package information, you'll want to include a small description of the incident.
799 Here's an example:
800 </p>
801
802 <figure link="/images/docs/bugzie-summary.png" caption="Summary"/>
803
804 <p>
805 Just these simple rules can make handling bugs a lot easier. Next are the
806 details. Here we put in the information about the bug. We'll demonstrate with an
807 example:
808 </p>
809
810 <figure link="/images/docs/bugzie-details.png" caption="Details"/>
811
812 <p>
813 So now the developer knows why we're filing the bug. They can then try to
814 reproduce it. Reproducibility tells us how often we were able to make the
815 problem recur. In this example, we can reproduce it any time simply by running
816 foobar2. Let's put that information in:
817 </p>
818
819 <figure link="/images/docs/bugzie-reprod.png" caption="Reproduction"/>
820
821 <p>
822 So now we have explained how we found the bug. Next we want to explain what
823 the results were and what we think they should be:
824 </p>
825
826 <figure link="/images/docs/bugzie-results.png" caption="Results"/>
827
828 <p>
829 Next we put additional information. This can be things such as stack traces,
830 <b>sections</b> of strace logs, but most importantly, your emerge --info output.
831 Here's an example:
832 </p>
833
834 <figure link="/images/docs/bugzie-addl-info.png" caption="Additional Information"/>
835
836 <p>
837 Lastly we select the severity of the bug. Please look this over carefully. In
838 most cases it's OK to leave it as is and someone will raise/lower it for you.
839 However, if you raise the severity of the bug, please make sure you read it over
840 carefully and make sure you're not making a mistake. Here we will set it to the
841 default of normal:
842 </p>
843
844 <figure link="/images/docs/bugzie-sev.png" caption="Severity"/>
845
846 <p>
847 Now we can submit the bug report by clicking on the Submit Bug Report box. You
848 will now see your new bug come up. See <uri
849 link="https://bugs.gentoo.org/show_bug.cgi?id=97265">Bug 97561</uri> for what
850 the result looks like. We've reported our bug! Now let's see how it's dealt
851 with.
852 </p>
853
854 </body>
855 </section>
856 </chapter>
857
858 <chapter>
859 <title>Working With Your Bug</title>
860 <section>
861 <body>
862
863 <p>
864 looking at the bug, we see the information we provided earlier:
865 </p>
866
867 <figure link="/images/docs/bugzie-new-basic.png" caption="New Bug Basic Information"/>
868
869 <p>
870 And our details are there too:
871 </p>
872
873 <figure link="/images/docs/bugzie-new-details.png" caption="New Bug Details"/>
874
875 <p>
876 Now as you can see, the bug has been assigned to bug-wranglers@gentoo.org. This
877 is the default location for Application component bugs. However, bug-wranglers
878 (usually) won't fix our bugs, so we'll reassign it to someone that can (you can
879 let bug-wranglers re-assign it for you as well). For this we use the package's
880 metadata.xml. You can normally find them in
881 /usr/portage/category/package/metadata.xml. Here's one I've made up for foobar2:
882 </p>
883
884 <pre caption="metadata.xml">
885 &lt;?xml version="1.0" encoding="UTF-8"?&gt;
886 &lt;!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"&gt;
887 &lt;pkgmetadata&gt;
888 &lt;herd&gt;chriswhite&lt;/herd&gt;
889 &lt;maintainer&gt;
890 &lt;email&gt;chriswhite@gentoo.org&lt;/email&gt;
891 &lt;name&gt;Chris White&lt;/name&gt;
892 &lt;/maintainer&gt;
893 &lt;longdescription lang="en"&gt;
894 Foobar2 is a package that uses a configuration file to display a word.
895 &lt;/longdescription&gt;
896 &lt;/pkgmetadata&gt;
897 </pre>
898
899 <p>
900 Notice the maintainer section.T his lists the maintainer of the package, which
901 in this case is myself, Chris White. The email listed is chriswhite@gentoo.org.
902 We will use this to re-assign the bug to the proper person. To do this, click
903 the bubble next to Reassign bug to, then fill in the email:
904 </p>
905
906 <note>
907 A package without a metadata.xml file should be re-assigned to
908 maintainer-needed@gentoo.org.
909 </note>
910
911 <figure link="/images/docs/bugzie-reassign.png" caption="Bug Reassignment"/>
912
913 <p>
914 Then hit the Commit button for the changes to take place. The bug has been
915 reassigned to me. Shortly afterward, you notice (by email usually) that I've
916 responded to your bug. I've stated that I'd like to see an strace log to figure
917 out how the program is trying to reach your configuration file. You follow the
918 previous instructions on using strace and obtain an strace log. Now you need to
919 attach it to the bug. In order to do this, click on "Create A New Attachment".
920 </p>
921
922 <figure link="/images/docs/bugzie-new-attach.png" caption="New Attachment"/>
923
924 <p>
925 Now we have to attach the log. We click on the "Browse..." button under "File"
926 and select the strace log. For Description, we'll put "strace log". Content-Type
927 is what kind of file we're attaching. A common mistake is to set it to
928 auto. In most cases it's best to manually set it. Our log file is a
929 plain text file, so we select "plain text (text/plain)". Obsoletes are for when
930 you are attaching a revision to a previously attached file. You can simply click
931 a check box next to the old file and Bugzilla will cross it out in the bug,
932 indicating that the attachment has been obsoleted. Reassignment means you want
933 to take the bug yourself. I rarely tend to use this.. and I don't think you will
934 need to at some point (unless you create great patches and we don't care about
935 you taking our bugs ;). Comments are for leaving comments about the file you're
936 posting. We'll put "Here is the strace file you requested". Now we have
937 something like this:
938 </p>
939
940 <figure link="/images/docs/bugzie-new-attach-comp.png" caption="New Attachment Completed"/>
941
942 <p>
943 We Submit the patch and it is now reflected on the bug report.
944 </p>
945
946 <figure link="/images/docs/bugzie-strace.png" caption="Attached strace log"/>
947
948 <p>
949 Now, while we're waiting another person notices your bug during step 1 of the
950 Guided Format. This person wants to see the status of the bug as well. He or
951 she may do so by putting their email in the Add CC field like so:
952 </p>
953
954 <figure link="/images/docs/bugzie-add-email.png" caption="Adding Email To CC:"/>
955
956 <note>
957 Email addresses must be registered with bugzilla. In order to CC multiple
958 addresses, simply separate them with commas or spaces.
959 </note>
960
961 <p>
962 After all this work, the bug can undergo various status markings. Here's a few:
963 </p>
964
965 <ul>
966 <li>
967 UNCONFIRMED - You're generally not going to see this too often. This
968 means that a bug reporter has opened a bug using the advanced method and is
969 uncertain his or her bug is an actual bug.
970 </li>
971 <li>
972 NEW - Bugs that are first opened are considered new.
973 </li>
974 <li>
975 ASSIGNED - When the person you've assigned the bug too validates your
976 bug, it will often receive ASSIGNED status while they figure out the issue.
977 This let's you know that they've accepted your bug as a real bug.
978 </li>
979 <li>
980 REOPENED - Someone has resolved a bug and you think the solution is not
981 feasible or the problem still persists. At this point, you may re-open the
982 bug. However <b>please do not abuse this</b>. If a developer closes the bug a
983 second or even third time, chances are that your bug is closed.
984 </li>
985 </ul>
986
987 <p>
988 Now shortly afterward, I find the error in the strace log. I resolve the bug
989 as RESOLVED FIXED and say that there was a change in the location of
990 configuration files, and that I will update the ebuild with a warning about it.
991 The bug now becomes resolved, and you are displayed with this:
992 </p>
993
994 <figure link="/images/docs/bugzie-reso.png" caption="Resolved Bug"/>
995
996 <p>
997 Also note the section here:
998 </p>
999
1000 <figure link="/images/docs/bugzie-options.png" caption="Bug Options"/>
1001
1002 <p>
1003 This gives you the option of Reopening the bug if you wish to (i.e. the developer
1004 thinks it's resolved but it's really not to your standards). Now our bug is
1005 fixed! However, different resolutions can occur. Here's a small list:
1006 </p>
1007
1008 <ul>
1009 <li>
1010 FIXED - The bug is fixed, follow the instructions to resolve your
1011 issue.
1012 </li>
1013 <li>
1014 INVALID - You did not do something specifically documented, causing the
1015 bug
1016 </li>
1017 <li>
1018 DUPLICATE - You didn't use this guide and reported a duplicate bug
1019 :)
1020 </li>
1021 <li>
1022 WORKSFORME - Developer/person assigned the bug cannot reproduce your
1023 error
1024 </li>
1025 </ul>
1026
1027 </body>
1028 </section>
1029
1030 <section>
1031 <title>Conclusion</title>
1032 <body>
1033
1034 <p>
1035 This concludes the howto on working with Bugzilla. I hope you find this useful.
1036 If you have any questions, comments, or ideas regarding this document, please
1037 send them to me at <mail
1038 link="chriswhite@gentoo.org">chriswhite@gentoo.org</mail>. Special
1039 thanks go to moreon for his notes on -g flags and compile errors, the people at
1040 #gentoo-bugs for helping out with bug-wrangling, and Griffon26 for his notes on
1041 maintainer-needed.
1042 </p>
1043
1044 </body>
1045 </section>
1046 </chapter>
1047 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20