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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.4 Revision 1.5
1<?xml version="1.0" encoding="UTF-8"?> 1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 2<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.4 2005/07/10 14:13:08 fox2mike Exp $ --> 3<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.5 2005/07/22 23:46:11 neysx Exp $ -->
4 4
5<guide link="/doc/en/bugzilla-howto.xml"> 5<guide link="/doc/en/bugzilla-howto.xml">
6<title>Gentoo Bug Reporting Guide</title> 6<title>Gentoo Bug Reporting Guide</title>
7 7
8<author title="Author"> 8<author title="Author">
9 <mail link="chriswhite@gentoo.org">Chris White</mail> 9 <mail link="chriswhite@gentoo.org">Chris White</mail>
10</author> 10</author>
11<author title="Editor"> 11<author title="Editor">
12 <mail link="fox2mike@gentoo.org">Shyam Mani</mail> 12 <mail link="fox2mike@gentoo.org">Shyam Mani</mail>
13</author> 13</author>
14 14
15<abstract> 15<abstract>
16This document shows the proper method of reporting bugs using Bugzilla. 16This document shows the proper method of reporting bugs using Bugzilla.
17</abstract> 17</abstract>
18 18
19<!-- The content of this document is licensed under the CC-BY-SA license --> 19<!-- The content of this document is licensed under the CC-BY-SA license -->
20<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> 20<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
21<license/> 21<license/>
22 22
23<version>1.3</version> 23<version>1.4</version>
24<date>2005-07-10</date> 24<date>2005-07-22</date>
25 25
26<chapter> 26<chapter>
27<title>Introduction</title> 27<title>Introduction</title>
28<section> 28<section>
29<title>Preface</title> 29<title>Preface</title>
30<body> 30<body>
31 31
32<p> 32<p>
33One of the factors that delay a bug being fixed is the way it is reported. By 33One of the factors that delay a bug being fixed is the way it is reported. By
34creating this guide, we hope to help improve the communication between 34creating this guide, we hope to help improve the communication between
35developers and users in bug resolution. Getting bugs fixed is an important, if 35developers and users in bug resolution. Getting bugs fixed is an important, if
36not crucial part of the quality assurance for any project and hopefully this 36not crucial part of the quality assurance for any project and hopefully this
37guide will help make that a success. 37guide will help make that a success.
38</p> 38</p>
39 39
74main.cc: In member function `void OXMain::DoOpen()': 74main.cc: In member function `void OXMain::DoOpen()':
75main.cc:323: warning: unused variable `FILE*fp' 75main.cc:323: warning: unused variable `FILE*fp'
76main.cc: In member function `void OXMain::DoSave(char*)': 76main.cc: In member function `void OXMain::DoSave(char*)':
77main.cc:337: warning: unused variable `FILE*fp' 77main.cc:337: warning: unused variable `FILE*fp'
78make[1]: *** [main.o] Error 1 78make[1]: *** [main.o] Error 1
79make[1]: Leaving directory 79make[1]: Leaving directory
80`/var/tmp/portage/xclass-0.7.4/work/xclass-0.7.4/example-app' 80`/var/tmp/portage/xclass-0.7.4/work/xclass-0.7.4/example-app'
81make: *** [shared] Error 2 81make: *** [shared] Error 2
82 82
83!!! ERROR: x11-libs/xclass-0.7.4 failed. 83!!! ERROR: x11-libs/xclass-0.7.4 failed.
84!!! Function src_compile, Line 29, Exitcode 2 84!!! Function src_compile, Line 29, Exitcode 2
85!!! 'emake shared' failed 85!!! 'emake shared' failed
86</pre> 86</pre>
87 87
88<p> 88<p>
89These errors can be quite troublesome. However, once you find them, what do 89These errors can be quite troublesome. However, once you find them, what do you
90you do? The following sections will look at two important tools for handling 90do? The following sections will look at two important tools for handling run
91run time errors. After that, we'll take a look at compile errors, and how to 91time errors. After that, we'll take a look at compile errors, and how to handle
92handle them. Let's start out with the first tool for debugging run time 92them. Let's start out with the first tool for debugging run time errors --
93errors -- <c>gdb</c>. 93<c>gdb</c>.
94</p> 94</p>
95 95
96</body> 96</body>
97</section> 97</section>
98</chapter> 98</chapter>
99 99
100 100
101<chapter> 101<chapter>
102<title>Debugging using GDB</title> 102<title>Debugging using GDB</title>
103<section> 103<section>
104<title>Introduction</title> 104<title>Introduction</title>
105<body> 105<body>
106 106
107<p> 107<p>
108GDB, or the (G)NU (D)e(B)ugger, is a program used to find run time errors that 108GDB, or the (G)NU (D)e(B)ugger, is a program used to find run time errors that
109normally involve memory corruption. First off, let's take a look at what 109normally involve memory corruption. First off, let's take a look at what
110debugging entails. One of the main things you must do in order to debug a 110debugging entails. One of the main things you must do in order to debug a
111program is to <c>emerge</c> the program with <c>FEATURES="nostrip"</c>. This 111program is to <c>emerge</c> the program with <c>FEATURES="nostrip"</c>. This
112prevents the stripping of debug symbols. Why are programs stripped by default? 112prevents the stripping of debug symbols. Why are programs stripped by default?
113The reason is the same as that for having gzipped man pages -- saving space. 113The reason is the same as that for having gzipped man pages -- saving space.
114Here's how the size of a program varies with and without debug symbol stripping. 114Here's how the size of a program varies with and without debug symbol stripping.
115</p> 115</p>
116 116
117<pre caption="Filesize Comparison"> 117<pre caption="Filesize Comparison">
118<comment>(debug symbols stripped)</comment> 118<comment>(debug symbols stripped)</comment>
119-rwxr-xr-x 1 chris users 3140 6/28 13:11 bad_code 119-rwxr-xr-x 1 chris users 3140 6/28 13:11 bad_code
120<comment>(debug symbols intact)</comment> 120<comment>(debug symbols intact)</comment>
121-rwxr-xr-x 1 chris users 6374 6/28 13:10 bad_code 121-rwxr-xr-x 1 chris users 6374 6/28 13:10 bad_code
122</pre> 122</pre>
123 123
124<p> 124<p>
125Just for reference, <e>bad_code</e> is the program we'll be debugging with 125Just for reference, <e>bad_code</e> is the program we'll be debugging with
126<c>gdb</c> later on. As you can see, the program without debugging symbols is 126<c>gdb</c> later on. As you can see, the program without debugging symbols is
1273140 bytes, while the program with them is 6374 bytes. That's close to double 1273140 bytes, while the program with them is 6374 bytes. That's close to double
128the size! Two more things can be done for debugging. The first is adding ggdb3 128the size! Two more things can be done for debugging. The first is adding ggdb3
129to your CFLAGS and CXXFLAGS. This flag adds more debugging information than is 129to your CFLAGS and CXXFLAGS. This flag adds more debugging information than is
130generally included. We'll see what that means later on. This is how 130generally 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. 131<path>/etc/make.conf</path> <e>might</e> look with the newly added flags.
132</p> 132</p>
133 133
134<pre caption="make.conf settings"> 134<pre caption="make.conf settings">
135CFLAGS="-O2 -pipe -ggdb3" 135CFLAGS="-O2 -pipe -ggdb3"
136CXXFLAGS="${CFLAGS}" 136CXXFLAGS="${CFLAGS}"
137</pre> 137</pre>
138 138
139<p> 139<p>
140Lastly, you can also add debug to the package's USE flags. This can be done with the 140Lastly, you can also add debug to the package's USE flags. This can be done
141<path>package.use</path> file. 141with the <path>package.use</path> file.
142</p> 142</p>
143 143
144<pre caption="Using package.use to add debug USE flag"> 144<pre caption="Using package.use to add debug USE flag">
145# <i>echo "category/package debug" >> /etc/portage/package.use</i> 145# <i>echo "category/package debug" >> /etc/portage/package.use</i>
146</pre> 146</pre>
147 147
148<note> 148<note>
149The directory <path>/etc/portage</path> does not exist by default and you may 149The directory <path>/etc/portage</path> does not exist by default and you may
150have to create it, if you have not already done so. If the package already has 150have to create it, if you have not already done so. If the package already has
151USE flags set in <path>package.use</path>, you will need to manually modify them 151USE flags set in <path>package.use</path>, you will need to manually modify them
152in your favorite editor. 152in your favorite editor.
153</note> 153</note>
154 154
155<p> 155<p>
156Then we re-emerge the package with the modifications we've done so far as shown 156Then we re-emerge the package with the modifications we've done so far as shown
157below. 157below.
383This creates a file called <path>strace.log</path> in the current directory. We 383This creates a file called <path>strace.log</path> in the current directory. We
384check the file, and shown below are the relevant parts from the file. 384check the file, and shown below are the relevant parts from the file.
385</p> 385</p>
386 386
387<pre caption="A Look At the strace Log"> 387<pre caption="A Look At the strace Log">
388open(".foobar2/config", O_RDONLY) = 3 388open(".foobar2/config", O_RDONLY) = 3
389read(3, "bar", 3) = 3 389read(3, "bar", 3) = 3
390</pre> 390</pre>
391 391
392<p> 392<p>
393Aha! So There's the problem. Someone moved the configuration directory to 393Aha! 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 394<path>.foobar2</path> instead of <path>.foobar</path>. We also see the program
395reading in "bar" as it should. In this case, we can recommend the ebuild 395reading in "bar" as it should. In this case, we can recommend the ebuild
396maintainer to put a warning about it. For now though, we can copy over the 396maintainer to put a warning about it. For now though, we can copy over the
397config file from <path>.foobar</path> and modify it to produce the correct 397config file from <path>.foobar</path> and modify it to produce the correct
398results. 398results.
399</p> 399</p>
400 400
401</body> 401</body>
402</section> 402</section>
403<section> 403<section>
404<title>Conclusion</title> 404<title>Conclusion</title>
405<body> 405<body>
406 406
407<p> 407<p>
408Now we've taken care of finding run time bugs. These bugs prove to be 408Now we've taken care of finding run time bugs. These bugs prove to be
409problematic when you try and run your programs. However, run time errors are 409problematic when you try and run your programs. However, run time errors are
410the least of your concerns if your program won't compile at all. Let's take a 410the least of your concerns if your program won't compile at all. Let's take a
411look at how to address <c>emerge</c> compile errors. 411look at how to address <c>emerge</c> compile errors.
412</p> 412</p>
413 413
498what version of the package is failing. As a side note, make is commonly used as 498what version of the package is failing. As a side note, make is commonly used as
499the build process for programs (<b>but not always</b>). If you can't find a 499the 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 500"make: ***" error anywhere, then simply copy and paste 20 lines before the
501emerge error. This should take care of most all build system error messages. Now 501emerge error. This should take care of most all build system error messages. Now
502let's say the errors seem to be quite large. 10 lines won't be enough to catch 502let's say the errors seem to be quite large. 10 lines won't be enough to catch
503everything. That's where PORT_LOGDIR comes into play. 503everything. That's where PORT_LOGDIR comes into play.
504</p> 504</p>
505 505
506</body> 506</body>
507</section> 507</section>
508<section> 508<section>
509<title>emerge and PORT_LOGDIR</title> 509<title>emerge and PORT_LOGDIR</title>
510<body> 510<body>
511 511
512<p> 512<p>
513PORT_LOGDIR is a portage variable that sets up a log directory for separate 513PORT_LOGDIR is a portage variable that sets up a log directory for separate
514emerge logs. Let's take a look and see what that entails. First, run your emerge 514emerge logs. Let's take a look and see what that entails. First, run your
515with PORT_LOGDIR set to your favorite log location. Let's say we have a 515emerge with PORT_LOGDIR set to your favorite log location. Let's say we have a
516location <path>/var/log/portage</path>. We'll use that for our log directory: 516location <path>/var/log/portage</path>. We'll use that for our log directory:
517</p> 517</p>
518 518
519<note> 519<note>
520In the default setup, <path>/var/log/portage</path> does not exist, and you will 520In the default setup, <path>/var/log/portage</path> does not exist, and you will
521most likely have to create it. If you do not, portage will fail to write the 521most likely have to create it. If you do not, portage will fail to write the
522logs. 522logs.
523</note> 523</note>
524 524
525<pre caption="emerge-ing With PORT_LOGDIR"> 525<pre caption="emerge-ing With PORT_LOGDIR">
526# <i>PORT_LOGDIR=/var/log/portage emerge foobar2</i> 526# <i>PORT_LOGDIR=/var/log/portage emerge foobar2</i>
527</pre> 527</pre>
528 528
529<p> 529<p>
530Now the emerge fails again. However, this time we have a log we can work with, 530Now the emerge fails again. However, this time we have a log we can work with,
627<note> 627<note>
628If you've used the Advanced Search before, you'll most likely see that screen 628If you've used the Advanced Search before, you'll most likely see that screen
629instead. 629instead.
630</note> 630</note>
631 631
632<p> 632<p>
633Proceed by clicking on the "Advanced Search" link to bring up the Advanced 633Proceed by clicking on the "Advanced Search" link to bring up the Advanced
634Search page. 634Search page.
635</p> 635</p>
636 636
637<figure link="/images/docs/bugzie-adv-search.png" caption="Advanced Search Page"/> 637<figure link="/images/docs/bugzie-adv-search.png" caption="Advanced Search Page"/>
638 638
639<p> 639<p>
640This is how the Advanced Search Page looks like. While it may seem overwhelming 640This is how the Advanced Search Page looks like. While it may seem overwhelming
641at first, we're going to look at a few simple areas to narrow down the rather 641at first, we're going to look at a few simple areas to narrow down the rather
642vague searches bugzilla returns. 642vague searches bugzilla returns.
643</p> 643</p>
644 644
645<figure link="/images/docs/bugzie-content.png" caption="Content"/> 645<figure link="/images/docs/bugzie-content.png" caption="Content"/>
646 646
647<p> 647<p>
648The first field is the summary of the bug. Here we're simply going to put the 648The first field is the summary of the bug. Here we're simply going to put the
649name of the package that's crashing. If bugzie doesn't return results, try 649name of the package that's crashing. If bugzie doesn't return results, try
650removing the package name, just in case someone didn't put that in the summary 650removing the package name, just in case someone didn't put that in the summary
651(highly unlikely, but we've seen a fair share of strange bug reports). 651(highly unlikely, but we've seen a fair share of strange bug reports).
652</p> 652</p>
653 653
654<p> 654<p>
655Product, Component, and Version should all be set to the default. This 655Product, Component, and Version should all be set to the default. This
656prevents us from being too specific and missing all the bugs. 656prevents us from being too specific and missing all the bugs.
657</p> 657</p>
747 747
748<p> 748<p>
749As you can see, <b>major</b> emphasis has been placed on putting your bug in the 749As you can see, <b>major</b> emphasis has been placed on putting your bug in the
750right place. Gentoo Linux is where a large majority of bugs go. 750right place. Gentoo Linux is where a large majority of bugs go.
751</p> 751</p>
752 752
753<p> 753<p>
754Despite this, some people will file ebuild bugs in portage development 754Despite this, some people will file ebuild bugs in portage development
755(assumption that portage team handles the portage tree) or infra (assumption 755(assumption that portage team handles the portage tree) or infra (assumption
756that infra has access to mirrors and rsync and can fix it directly). This is 756that infra has access to mirrors and rsync and can fix it directly). This is
757simply not how things work. 757simply not how things work.
758</p> 758</p>
759 759
760<p> 760<p>
761Another common misconception occurs with our Documentation bugs. For example, a 761Another common misconception occurs with our Documentation bugs. For example, a
762user finds a bug with the <uri 762user finds a bug with the <uri link="/proj/en/releng/catalyst/">Catalyst
763link="http://www.gentoo.org/proj/en/releng/catalyst/index.xml">Catalyst
764Docs</uri>. The general tendency is to file a bug under Docs-user, which gets 763Docs</uri>. The general tendency is to file a bug under Docs-user, which gets
765assigned to the <uri link="http://gdp.gentoo.org">GDP</uri>, when it should 764assigned to the <uri link="http://gdp.gentoo.org">GDP</uri>, when it should
766actually go to a member of the <uri 765actually go to a member of the <uri link="/proj/en/releng/">Release
767link="http://www.gentoo.org/proj/en/releng/">Release Engineering</uri> team. As 766Engineering</uri> team. As a rule of thumb, only documentation under
768a rule of thumb, only documentation under http://www.gentoo.org/doc/* is under 767<path>http://www.gentoo.org/doc/*</path> is under the GDP. Anything under
769the GDP. Anything under http://www.gentoo.org/proj/* is under the respective 768<path>http://www.gentoo.org/proj/*</path> is under the respective teams.
770teams.
771</p> 769</p>
772 770
773<note> 771<note>
774We would rather see a bug whose product was not supposed to be Gentoo Linux but 772We would rather see a bug whose product was not supposed to be Gentoo Linux but
775has been filed under the same rather than seeing a bug which belongs the Gentoo 773has been filed under the same rather than seeing a bug which belongs the Gentoo
776Linux product and filed elsewhere. While neither is preferred, the former is more 774Linux product and filed elsewhere. While neither is preferred, the former is more
777acceptable and understandable (except website bugs.. we might have an issue with 775acceptable and understandable (except website bugs.. we might have an issue with
778that...). 776that...).
779</note> 777</note>
780 778
781<p> 779<p>
782Our bug goes in Gentoo Linux as it's an ebuild bug. We head over there and are presented 780Our bug goes in Gentoo Linux as it's an ebuild bug. We head over there and are
783with the multi-step bug reporting process. Let us now proceed with Step 1... 781presented with the multi-step bug reporting process. Let us now proceed with
782Step 1...
784</p> 783</p>
785 784
786<figure link="/images/docs/bugzie-guide-step1.png" caption="Guided Format Step 1"/> 785<figure link="/images/docs/bugzie-guide-step1.png" caption="Guided Format Step 1"/>
787 786
788<p> 787<p>
789The first step here is really important (as the red text tells you). This is 788The first step here is really important (as the red text tells you). This is
790where you search to see that someone else hasn't hit the same bug you have, yet. 789where you search to see that someone else hasn't hit the same bug you have, yet.
791If you do skip this step and a bug like yours already exists, it will be marked 790If you do skip this step and a bug like yours already exists, it will be marked
792as a DUPLICATE thus wasting a large amount of QA effort. To give you an idea, 791as a DUPLICATE thus wasting a large amount of QA effort. To give you an idea,
793the bug numbers that are struck out above are duplicate bugs. Now comes step 2, 792the bug numbers that are struck out above are duplicate bugs. Now comes step 2,
794where we give the information. 793where we give the information.
795</p> 794</p>
796 795
797</body> 796</body>
798</section> 797</section>
799<section> 798<section>
800<title>Required Information</title> 799<title>Required Information</title>
801<body> 800<body>
802 801
803<figure link="/images/docs/bugzie-basic.png" caption="Basic Information"/> 802<figure link="/images/docs/bugzie-basic.png" caption="Basic Information"/>
804 803
805<p> 804<p>
806Let us take a closer look at what's what. 805Let us take a closer look at what's what.
807</p> 806</p>
808 807
809<ul> 808<ul>
810 <li> 809 <li>
811 First, there's the Product. The product will narrow down the bug to a 810 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), 811 specific area of Gentoo like Bugzilla (for bugs relating to
813 Docs-user(for User Documentation) or Gentoo Linux (for ebuilds and the like). 812 bugs.gentoo.org), Docs-user(for User Documentation) or Gentoo Linux (for
814 </li> 813 ebuilds and the like).
815 <li> 814 </li>
815 <li>
816 Component is where exactly the problem occurs, more specifically which part 816 Component is where exactly the problem occurs, more specifically which part
817 of selected product the bug comes under. This makes classification easier. 817 of selected product the bug comes under. This makes classification easier.
818 </li>
819 <li> 818 </li>
819 <li>
820 Hardware platform is what architecture you're running. If you were running 820 Hardware platform is what architecture you're running. If you were running
821 SPARC, you would set it to SPARC. 821 SPARC, you would set it to SPARC.
822 </li>
823 <li> 822 </li>
823 <li>
824 Operating System is what Operating System you're using. Because Gentoo is 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 825 considered a "Meta-distribution", it can run on other operating systems
826 beside Linux. 826 beside Linux.
827 </li> 827 </li>
828</ul> 828</ul>
829 829
830<p> 830<p>
831So, for our example bug, we have : 831So, for our example bug, we have :
832</p> 832</p>
833 833
834<ul> 834<ul>
835 <li>
836 Product - Gentoo Linux (Since it is an ebuild issue) 835 <li>Product - Gentoo Linux (Since it is an ebuild issue)</li>
837 </li>
838 <li>
839 Component - Application (It is an application at fault, foobar2) 836 <li>Component - Application (It is an application at fault, foobar2)</li>
840 </li>
841 <li>
842 Hardware Platform - All (This error could occur across architectures) 837 <li>Hardware Platform - All (This error could occur across architectures)</li>
843 </li>
844 <li>
845 Operation System - All (It could occur on all types of systems) 838 <li>Operation System - All (It could occur on all types of systems)</li>
846 </li>
847</ul> 839</ul>
848 840
849<figure link="/images/docs/bugzie-basic-comp.png" caption="Completed Basic Information"/> 841<figure link="/images/docs/bugzie-basic-comp.png" caption="Completed Basic Information"/>
850 842
851<ul> 843<ul>
852 <li> 844 <li>
853 Build Identifier is basically the User Agent of the browser that is being used 845 Build Identifier is basically the User Agent of the browser that is being
854 to report the bugs (for logging purposes). You can just leave this as is. 846 used to report the bugs (for logging purposes). You can just leave this as
855 </li> 847 is.
856 <li> 848 </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> 849 <li>
850 URL is optional and is used to point to errors on a site someplace
851 (pastebin, etc.). However, doing it inside the bug allows the developers be
852 able to reference to it at any time and is preferred.
861 <li> 853 </li>
854 <li>
862 In the Summary, you should put the package category, name, and number. 855 In the Summary, you should put the package category, name, and number.
863 </li> 856 </li>
864</ul> 857</ul>
865 858
866<p> 859<p>
867Not including the category in the summary really isn't too bad, but it's 860Not including the category in the summary really isn't too bad, but it's
868recommended. If you don't include the package name, however, we won't know what 861recommended. If you don't include the package name, however, we won't know what
869you're filling a bug for, and will have to ask you about it later. The version 862you're filling a bug for, and will have to ask you about it later. The version
870number is important for people searching for bugs. If 20 people filed bugs and 863number is important for people searching for bugs. If 20 people filed bugs and
871not one put a version number, how would people looking for similar bugs be able 864not one put a version number, how would people looking for similar bugs be able
872to tell if one was there's? They'd have to look through every single bug, which 865to tell if one was there's? They'd have to look through every single bug, which
873isn't too hard, but if there are say, 200 bugs.. it's not that easy. After all 866isn't too hard, but if there are say, 200 bugs.. it's not that easy. After all
874the package information, you'll want to include a small description of the 867the package information, you'll want to include a small description of the
875incident. Here's an example: 868incident. Here's an example:
876</p> 869</p>
877 870
889reproduce it. Reproducibility tells us how often we were able to make the 882reproduce it. Reproducibility tells us how often we were able to make the
890problem recur. In this example, we can reproduce it any time simply by running 883problem recur. In this example, we can reproduce it any time simply by running
891foobar2. Let's put that information in. 884foobar2. Let's put that information in.
892</p> 885</p>
893 886
894<figure link="/images/docs/bugzie-reprod.png" caption="Reproduction"/> 887<figure link="/images/docs/bugzie-reprod.png" caption="Reproduction"/>
895 888
896<p> 889<p>
897We have explained how we found the bug. The next step is to explain what were 890We have explained how we found the bug. The next step is to explain what were
898the results we got and what we think they should actually be. 891the results we got and what we think they should actually be.
899</p> 892</p>
900 893
901<figure link="/images/docs/bugzie-results.png" caption="Results"/> 894<figure link="/images/docs/bugzie-results.png" caption="Results"/>
902 895
903<p> 896<p>
904We could then provide additional information. This could be things such as stack traces, 897We could then provide additional information. This could be things such as
905<b>sections</b> (since the whole log is usually big and of not much use) of 898stack traces, <b>sections</b> (since the whole log is usually big and of not
906strace logs, but most importantly, your <c>emerge --info</c> output. Here's an 899much use) of strace logs, but most importantly, your <c>emerge --info</c>
907example. 900output. Here's an example.
908</p> 901</p>
909 902
910<figure link="/images/docs/bugzie-addl-info.png" caption="Additional Information"/> 903<figure link="/images/docs/bugzie-addl-info.png" caption="Additional Information"/>
911 904
912<p> 905<p>
913Lastly we select the severity of the bug. Please look this over carefully. In 906Lastly we select the severity of the bug. Please look this over carefully. In
914most cases it's OK to leave it as is and someone will raise/lower it for you. 907most cases it's OK to leave it as is and someone will raise/lower it for you.
915However, if you raise the severity of the bug, please make sure you read it over 908However, if you raise the severity of the bug, please make sure you read it over
916carefully and make sure you're not making a mistake. A run down of the various 909carefully and make sure you're not making a mistake. A run down of the various
917levels is given below. 910levels is given below.
918</p> 911</p>
919 912
920<ul> 913<ul>
921 <li> 914 <li>
922 Blocker - The program just plain doesn't want to emerge or is a major 915 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 916 hinderance to the system. For example a <c>baselayout</c> issue which
924 a system from booting up would be a sure candidate to be labelled blocker. 917 prevents a system from booting up would be a sure candidate to be labelled
925 </li> 918 blocker.
926 <li> 919 </li>
920 <li>
927 Critical - The program has loss of data or severe memory leaks during 921 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 922 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 923 compile could be labelled critical. It won't prevent the system from
930 up, but is quite essential for day to day stuff. 924 starting up, but is quite essential for day to day stuff.
931 </li>
932 <li> 925 </li>
926 <li>
933 Major - The program crashes, but nothing that causes your system severe 927 Major - The program crashes, but nothing that causes your system severe
934 damage or information loss. 928 damage or information loss.
935 </li>
936 <li> 929 </li>
930 <li>
937 Minor - Your program crashes here and there with apparent workarounds. 931 Minor - Your program crashes here and there with apparent workarounds.
938 </li>
939 <li> 932 </li>
933 <li>
940 Normal - The default. If you're not sure leave it here unless it's a new 934 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. 935 build or cosmetic change, then read below for more information.
942 </li>
943 <li> 936 </li>
944 Trivial - Things such as a mispelled word or whitespace clean up. 937 <li>Trivial - Things such as a mispelled word or whitespace clean up. </li>
945 </li> 938 <li>
946 <li>
947 Enhancement - A request to enable a new feature in a program, or more 939 Enhancement - A request to enable a new feature in a program, or more
948 specifically <e>new ebuilds</e>. 940 specifically <e>new ebuilds</e>.
949 </li> 941 </li>
950</ul> 942</ul>
951 943
952<figure link="/images/docs/bugzie-sev.png" caption="Severity"/> 944<figure link="/images/docs/bugzie-sev.png" caption="Severity"/>
953 945
954<p> 946<p>
955Here, we'll set it to Normal. 947Here, we'll set it to Normal.
956</p> 948</p>
957 949
958<p> 950<p>
959Now we can submit the bug report by clicking on the Submit Bug Report box. You 951Now we can submit the bug report by clicking on the Submit Bug Report box. You
960will now see your new bug come up. See <uri 952will now see your new bug come up. See <uri
961link="https://bugs.gentoo.org/show_bug.cgi?id=97265">Bug 97561</uri> for what 953link="https://bugs.gentoo.org/show_bug.cgi?id=97265">Bug 97561</uri> for what
962the result looks like. We've reported our bug! Now let's see how it's dealt 954the result looks like. We've reported our bug! Now let's see how it's dealt
963with. 955with.
1034reassigned to me. Shortly afterward, you notice (by email usually) that I've 1026reassigned to me. Shortly afterward, you notice (by email usually) that I've
1035responded to your bug. I've stated that I'd like to see an strace log to figure 1027responded to your bug. I've stated that I'd like to see an strace log to figure
1036out how the program is trying to reach your configuration file. You follow the 1028out how the program is trying to reach your configuration file. You follow the
1037previous instructions on using strace and obtain an strace log. Now you need to 1029previous instructions on using strace and obtain an strace log. Now you need to
1038attach it to the bug. In order to do this, click on "Create A New Attachment". 1030attach it to the bug. In order to do this, click on "Create A New Attachment".
1039</p> 1031</p>
1040 1032
1041<figure link="/images/docs/bugzie-new-attach.png" caption="New Attachment"/> 1033<figure link="/images/docs/bugzie-new-attach.png" caption="New Attachment"/>
1042 1034
1043<p> 1035<p>
1044Now we have to attach the log. Let's go throught it step wise. 1036Now we have to attach the log. Let's go throught it step wise.
1045</p> 1037</p>
1046 1038
1047<ul> 1039<ul>
1048 <li> 1040 <li>
1049 File - This is the location of the file in your machine. In this example, the 1041 File - This is the location of the file in your machine. In this example,
1050 location of <path>strace.log</path>. You can use the "Browse..." button to 1042 the location of <path>strace.log</path>. You can use the "Browse..." button
1051 select the file, or enter the path directly in the text field. 1043 to select the file, or enter the path directly in the text field.
1052 </li>
1053 <li> 1044 </li>
1045 <li>
1054 Description - A short one liner, or a few wors describing the attachment. 1046 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. 1047 We'll just enter strace.log here, since that's quite self-explanatory.
1056 </li>
1057 <li> 1048 </li>
1049 <li>
1058 Content Type - This is the type of the file we're attaching to the bug. 1050 Content Type - This is the type of the file we're attaching to the bug.
1059 </li>
1060 <li> 1051 </li>
1052 <li>
1061 Obsoletes - If there were attachements submitted to the bug before the current 1053 Obsoletes - If there were attachements submitted to the bug before the
1062 one, you have an option of declaring them obsoleted by yours. Since we have no 1054 current one, you have an option of declaring them obsoleted by yours. Since
1063 prior attachments to this bug, we need not bother. 1055 we have no prior attachments to this bug, we need not bother.
1064 </li>
1065 <li> 1056 </li>
1057 <li>
1066 Comment - Enter comments that will be visible along with the attachments. You 1058 Comment - Enter comments that will be visible along with the attachments.
1067 could elaborate on the attachment here, if needed. 1059 You could elaborate on the attachment here, if needed.
1068 </li> 1060 </li>
1069</ul> 1061</ul>
1070 1062
1071<p> 1063<p>
1072With respect to Content Type, here are a few more details. You can check the 1064With 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 1065"patch" checkbox if you're submitting a patch. Otherwise, you could ask
1074to "auto-detect" the file type (not advisable). The other options are "select 1066Bugzilla to "auto-detect" the file type (not advisable). The other options are
1075from list", which is most frequently used. Use plain text (text/plain) for <e>most</e> 1067"select from list", which is most frequently used. Use plain text (text/plain)
1076attachments except binary files like images (which can use image/gif, 1068for <e>most</e> attachments except binary files like images (which can use
1077image/jpeg or image/png depending on type) or compressed files like .tar.bz2 1069image/gif, image/jpeg or image/png depending on type) or compressed files like
1078which would use application/octet-stream as content type. 1070.tar.bz2 which would use application/octet-stream as content type.
1079</p> 1071</p>
1080 1072
1081 1073
1082<figure link="/images/docs/bugzie-new-attach-comp.png" caption="New Attachment Completed"/> 1074<figure link="/images/docs/bugzie-new-attach-comp.png" caption="New Attachment Completed"/>
1083 1075
1084<p> 1076<p>
1085We submit <path>strace.log</path> and it is reflected on the bug report. 1077We submit <path>strace.log</path> and it is reflected on the bug report.
1086</p> 1078</p>
1087 1079
1088<figure link="/images/docs/bugzie-strace.png" caption="Attached strace log"/> 1080<figure link="/images/docs/bugzie-strace.png" caption="Attached strace log"/>
1089 1081
1090<p> 1082<p>
1091We've mentioned before that sometimes ebuilds will tell you to attach a file in 1083We've mentioned before that sometimes ebuilds will tell you to attach a file in
1092the emerge error. An example can be seen below. 1084the emerge error. An example can be seen below.
1093</p> 1085</p>
1119 1111
1120<note> 1112<note>
1121Email addresses must be registered with Gentoo Bugzilla. In order to CC multiple 1113Email addresses must be registered with Gentoo Bugzilla. In order to CC multiple
1122addresses, simply separate them with commas or spaces. 1114addresses, simply separate them with commas or spaces.
1123</note> 1115</note>
1124 1116
1125<p> 1117<p>
1126After all this work, the bug can undergo various status markings. This is 1118After all this work, the bug can undergo various status markings. This is
1127usually done by the Gentoo Developers and sometimes by the reporter. The 1119usually done by the Gentoo Developers and sometimes by the reporter. The
1128following are the various possible states a bug may go through during its 1120following are the various possible states a bug may go through during its
1129lifetime. 1121lifetime.
1130</p> 1122</p>
1131 1123
1132<ul> 1124<ul>
1133 <li> 1125 <li>
1134 UNCONFIRMED - You're generally not going to see this too often. This 1126 UNCONFIRMED - You're generally not going to see this too often. This means
1135 means that a bug reporter has opened a bug using the advanced method and is 1127 that a bug reporter has opened a bug using the advanced method and is
1136 uncertain his or her bug is an actual bug. 1128 uncertain his or her bug is an actual bug.
1137 </li>
1138 <li> 1129 </li>
1139 NEW - Bugs that are first opened are considered new. 1130 <li>NEW - Bugs that are first opened are considered new.</li>
1140 </li> 1131 <li>
1141 <li>
1142 ASSIGNED - When the person you've assigned the bug too validates your 1132 ASSIGNED - When the person you've assigned the bug too validates your bug,
1143 bug, it will often receive ASSIGNED status while they figure out the issue. 1133 it will often receive ASSIGNED status while they figure out the issue.
1144 This lets you know that they've accepted your bug as a real bug. 1134 This lets you know that they've accepted your bug as a real bug.
1145 </li>
1146 <li> 1135 </li>
1136 <li>
1147 REOPENED - Someone has resolved a bug and you think the solution is not 1137 REOPENED - Someone has resolved a bug and you think the solution is not
1148 feasible or the problem still persists. At this point, you may re-open the 1138 feasible or the problem still persists. At this point, you may re-open the
1149 bug. Please <b>do not abuse this</b>. If a developer closes the bug a 1139 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. 1140 second or third time, chances are that your bug is closed.
1151 </li>
1152 <li> 1141 </li>
1142 <li>
1153 RESOLVED - A firm decision has been taken on the bug. Usually goes onto FIXED 1143 RESOLVED - A firm decision has been taken on the bug. Usually goes onto
1154 to indicate the bug is solved and the matter closed although various other 1144 FIXED to indicate the bug is solved and the matter closed although various
1155 resolutions are possible. We'll look into those a little later. 1145 other resolutions are possible. We'll look into those a little later.
1156 </li>
1157 <li> 1146 </li>
1147 <li>
1158 VERIFIED - The steps take to work the bug are correct. This is usually a QA 1148 VERIFIED - The steps take to work the bug are correct. This is usually a QA
1159 thing. 1149 thing.
1160 </li>
1161 <li> 1150 </li>
1151 <li>
1162 CLOSED - Basically means RIP for the bug and it's buried under the never ending 1152 CLOSED - Basically means RIP for the bug and it's buried under the never
1163 flow of new bugs. 1153 ending flow of new bugs.
1164 </li> 1154 </li>
1165</ul> 1155</ul>
1166 1156
1167<p> 1157<p>
1168Now shortly afterward, we find the error in the strace log and fix the bug and 1158Now shortly afterward, we find the error in the strace log and fix the bug and
1169mark it as RESOLVED FIXED and mention that there was a change in the location of 1159mark it as RESOLVED FIXED and mention that there was a change in the location
1170configuration files, and that I will update the ebuild with a warning about it. 1160of configuration files, and that I will update the ebuild with a warning about
1171The bug now becomes resolved, and you are shown the following. 1161it. The bug now becomes resolved, and you are shown the following.
1172</p> 1162</p>
1173 1163
1174<figure link="/images/docs/bugzie-reso.png" caption="Resolved Bug"/> 1164<figure link="/images/docs/bugzie-reso.png" caption="Resolved Bug"/>
1175 1165
1176<p> 1166<p>
1177A little below, you'll see the following: 1167A little below, you'll see the following:
1178</p> 1168</p>
1179 1169
1180<figure link="/images/docs/bugzie-options.png" caption="Bug Options"/> 1170<figure link="/images/docs/bugzie-options.png" caption="Bug Options"/>
1181 1171
1182<p> 1172<p>
1183This gives you the option of Reopening the bug if you wish to (i.e. the developer 1173This gives you the option of Reopening the bug if you wish to (i.e. the
1184thinks it's resolved but it's really not to your standards). Now our bug is 1174developer thinks it's resolved but it's really not to your standards). Now our
1185fixed! However, different resolutions can occur. Here's a small list: 1175bug is fixed! However, different resolutions can occur. Here's a small list:
1186</p> 1176</p>
1187 1177
1188<ul> 1178<ul>
1189 <li> 1179 <li>
1190 FIXED - The bug is fixed, follow the instructions to resolve your 1180 FIXED - The bug is fixed, follow the instructions to resolve your issue.
1191 issue.
1192 </li>
1193 <li> 1181 </li>
1182 <li>
1194 INVALID - You did not do something specifically documented, causing the 1183 INVALID - You did not do something specifically documented, causing the
1195 bug. 1184 bug.
1196 </li>
1197 <li> 1185 </li>
1198 DUPLICATE - You didn't use this guide and reported a duplicate bug 1186 <li>DUPLICATE - You didn't use this guide and reported a duplicate bug.</li>
1199 :)
1200 </li> 1187 <li>
1201 <li>
1202 WORKSFORME - Developer/person assigned the bug cannot reproduce your 1188 WORKSFORME - Developer/person assigned the bug cannot reproduce your error.
1203 error.
1204 </li>
1205 <li> 1189 </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> 1190 <li>
1191 CANTFIX - Somehow the bug cannot be solved because of certain
1192 circumstances. These circumstances will be noted by the person taking the
1193 bug.
1209 <li> 1194 </li>
1195 <li>
1210 WONTFIX - This is usually applied to new ebuilds or feature requests. 1196 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 1197 Basically the developer does not want to add a certain feature because it
1212 not needed, a better alternative exists, or it's just plain broken. Sometimes 1198 is not needed, a better alternative exists, or it's just plain broken.
1213 you may be given a solution to get said issue resolved. 1199 Sometimes you may be given a solution to get said issue resolved.
1214 </li>
1215 <li> 1200 </li>
1201 <li>
1216 UPSTREAM - The bug cannot be fixed by the Gentoo development team, and 1202 UPSTREAM - The bug cannot be fixed by the Gentoo development team, and have
1217 have requested you take the problem upstream (the people that actually made 1203 requested you take the problem upstream (the people that actually made the
1218 the program) for review. Upstream has a few ways of handling bugs. These 1204 program) for review. Upstream has a few ways of handling bugs. These
1219 include mailing lists, irc channels, and even bug reporting systems. If 1205 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 1206 you're not sure how to contact them, ask in the bug and someone will point
1221 you to the right direction. 1207 you to the right direction.
1222 </li> 1208 </li>
1223</ul> 1209</ul>
1224 1210
1225<p> 1211<p>
1226Sometimes, before the bug can be resolved, a developer may request that you 1212Sometimes, before the bug can be resolved, a developer may request that you
1227test an updated ebulid. In the next chapter we'll take a look at testing 1213test an updated ebulid. In the next chapter we'll take a look at testing
1228ebuilds. 1214ebuilds.
1229</p> 1215</p>
1230 1216
1231</body> 1217</body>
1232</section> 1218</section>
1233</chapter> 1219</chapter>
1234 1220
1235<chapter> 1221<chapter>
1236<title>Testing Ebuilds</title> 1222<title>Testing Ebuilds</title>
1321Calculating dependencies ...done! 1307Calculating dependencies ...done!
1322[ebuild N ] sys-apps/foobar2-1.0 0 kB [1] 1308[ebuild N ] sys-apps/foobar2-1.0 0 kB [1]
1323 1309
1324Total size of downloads: 0 kB 1310Total size of downloads: 0 kB
1325Portage overlays: 1311Portage overlays:
1326 [1] /usr/local/portage 1312 [1] /usr/local/portage
1327</pre> 1313</pre>
1328 1314
1329<p> 1315<p>
1330It does seem to have worked! You'll notice the [1] next to the [ebuild] line. 1316It does seem to have worked! You'll notice the [1] next to the [ebuild] line.
1331That points to <path>/usr/local/portage</path>, which is the overlay we created 1317That points to <path>/usr/local/portage</path>, which is the overlay we created
1332earlier. Now we go ahead and emerge the package. 1318earlier. Now we go ahead and emerge the package.
1333</p> 1319</p>
1334 1320
1335<pre caption="Emerge Result"> 1321<pre caption="Emerge Result">
1336# emerge foobar2 1322# <i>emerge foobar2</i>
1337 Calculating dependencies ...done! 1323 Calculating dependencies ...done!
1338<comment>(compile info snipped)</comment> 1324<comment>(compile info snipped)</comment>
1339>>> Unpacking foobar2-1.0.tar.bz2 to /var/tmp/portage/foobar2-1.0/work 1325>>> Unpacking foobar2-1.0.tar.bz2 to /var/tmp/portage/foobar2-1.0/work
1340 * Applying foobar2-1.0-Makefile.patch ... [ ok ] 1326 * Applying foobar2-1.0-Makefile.patch ... [ ok ]
1341<comment>(compile info snipped)</comment> 1327<comment>(compile info snipped)</comment>
1342>>> Merging sys-apps/foobar2-1.0 to / 1328>>> Merging sys-apps/foobar2-1.0 to /
1343>>> chris +sandbox(preinst) 1329>>> chris +sandbox(preinst)
1344--- /usr/ 1330--- /usr/
1345--- /usr/bin/ 1331--- /usr/bin/
1346>>> /usr/bin/foobar2 1332>>> /usr/bin/foobar2
1347</pre> 1333</pre>
1348 1334
1349<p> 1335<p>
1350In the first section we see that the emerge started off as it should. The second 1336In the first section we see that the emerge started off as it should. The second
1351section shows our patch being applied successfully by the "[ ok ]" status 1337section shows our patch being applied successfully by the "[ ok ]" status
1352message to the right. The last section tells us the program compiled ok. The 1338message to the right. The last section tells us the program compiled ok. The
1353patch works! Now we can go and let the developer know that their patch works 1339patch works! Now we can go and let the developer know that their patch works
1354fine, and that they can commit the fix to portage. 1340fine, and that they can commit the fix to portage.
1355</p> 1341</p>
1356 1342
1357</body> 1343</body>
1358</section> 1344</section>
1359<section> 1345<section>
1360<title>Conclusion</title> 1346<title>Conclusion</title>
1361<body> 1347<body>
1362 1348
1363<p> 1349<p>
1364This concludes the howto on working with Bugzilla. I hope you find this useful. 1350This concludes the howto on working with Bugzilla. I hope you find this useful.
1365If you have any questions, comments, or ideas regarding this document, please 1351If you have any questions, comments, or ideas regarding this document, please
1366send them to me at <mail 1352send them to me at <mail>chriswhite@gentoo.org</mail>. Special thanks go to
1367link="chriswhite@gentoo.org">chriswhite@gentoo.org</mail>. Special
1368thanks go to moreon for his notes on -g flags and compile errors, the people at 1353moreon for his notes on -g flags and compile errors, the people at #gentoo-bugs
1369#gentoo-bugs for helping out with bug-wrangling, Griffon26 for his notes on 1354for helping out with bug-wrangling, Griffon26 for his notes on
1370maintainer-needed, robbat2 for general suggestions and fox2mike for fixing up 1355maintainer-needed, robbat2 for general suggestions and fox2mike for fixing up
1371the doc and adding stuff as needed. 1356the doc and adding stuff as needed.
1372</p> 1357</p>
1373 1358
1374</body> 1359</body>
1375</section> 1360</section>
1376</chapter> 1361</chapter>
1377</guide> 1362</guide>

Legend:
Removed from v.1.4  
changed lines
  Added in v.1.5

  ViewVC Help
Powered by ViewVC 1.1.20