/[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.6 Revision 1.12
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.6 2005/08/30 02:51:12 vapier Exp $ --> 3<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.12 2008/02/01 19:30:40 jkt Exp $ -->
4 4
5<guide link="/doc/en/bugzilla-howto.xml"> 5<guide link="/doc/en/bugzilla-howto.xml">
6<title>Gentoo Bug Reporting Guide</title> 6<title>Gentoo Bug Reporting Guide</title>
7 7
8<author title="Author"> 8<author title="Author">
18 18
19<!-- The content of this document is licensed under the CC-BY-SA license --> 19<!-- The content of this document is licensed under the CC-BY-SA license -->
20<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> 20<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
21<license/> 21<license/>
22 22
23<version>1.5</version> 23<version>1.11</version>
24<date>2005-08-29</date> 24<date>2008-01-31</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>
308<comment>(-ggdb flag enabled)</comment> 308<comment>(-ggdb flag enabled)</comment>
309-rwxr-xr-x 1 chris users 19552 6/28 13:11 bad_code 309-rwxr-xr-x 1 chris users 19552 6/28 13:11 bad_code
310</pre> 310</pre>
311 311
312<p> 312<p>
313As you can see, -ggdb adds about <e>13178</e> more bytes to the file size over the one 313As you can see, -ggdb adds about <e>13178</e> more bytes to the file size over
314with debugging symbols. However, as shown above, this increase in file size can 314the one with debugging symbols. However, as shown above, this increase in file
315be worth it if presenting debug information to developers. The backtrace can be 315size can be worth it if presenting debug information to developers. The
316saved to a file by copying and pasting from the terminal (if it's a non-x based 316backtrace can be saved to a file by copying and pasting from the terminal (if
317terminal, you can use gpm. To keep this doc simple, I recommend you read up on 317it's a non-x based terminal, you can use gpm. To keep this doc simple, I
318recommend you read up on the <uri link="/doc/en/gpm.xml#doc_chap4">documentation
318the documentation for gpm to see how to copy and paste with it). Now that we're 319for gpm</uri> to see how to copy and paste with it). Now that we're done with
319done with <c>gdb</c>, we can quit. 320<c>gdb</c>, we can quit.
320</p> 321</p>
321 322
322<pre caption="Quitting GDB"> 323<pre caption="Quitting GDB">
323(gdb) <i>quit</i> 324(gdb) <i>quit</i>
324The program is running. Exit anyway? (y or n) <i>y</i> 325The program is running. Exit anyway? (y or n) <i>y</i>
845 Build Identifier is basically the User Agent of the browser that is being 846 Build Identifier is basically the User Agent of the browser that is being
846 used to report the bugs (for logging purposes). You can just leave this as 847 used to report the bugs (for logging purposes). You can just leave this as
847 is. 848 is.
848 </li> 849 </li>
849 <li> 850 <li>
850 URL is optional and is used to point to errors on a site someplace 851 URL is optional and is used to point to relevant information on another site
851 (pastebin, etc.). However, doing it inside the bug allows the developers be 852 (upstream bugzilla, release notes on package homepage etc.). You should
852 able to reference to it at any time and is preferred. 853 never use URL to point to pastebins for error messages, logs, <c>emerge
854 --info</c> output, screenshots or similar information. Instead, these should
855 always be attached to the bug.
853 </li> 856 </li>
854 <li> 857 <li>
855 In the Summary, you should put the package category, name, and number. 858 In the Summary, you should put the package category, name, and number.
856 </li> 859 </li>
857</ul> 860</ul>
951Now we can submit the bug report by clicking on the Submit Bug Report box. You 954Now we can submit the bug report by clicking on the Submit Bug Report box. You
952will now see your new bug come up. See <uri 955will now see your new bug come up. See <uri
953link="https://bugs.gentoo.org/show_bug.cgi?id=97265">Bug 97561</uri> for what 956link="https://bugs.gentoo.org/show_bug.cgi?id=97265">Bug 97561</uri> for what
954the result looks like. We've reported our bug! Now let's see how it's dealt 957the result looks like. We've reported our bug! Now let's see how it's dealt
955with. 958with.
959</p>
960
961</body>
962</section>
963<section>
964<title>Zero-day bump requests</title>
965<body>
966
967<p>
968So far, we've shown what to do when filing a bug. Now let's take a look at what
969<e>not</e> to do.
970</p>
971
972<p>
973Suppose that you've eagerly been following an upstream project's schedule, and
974when you check their homepage, guess what? They just released a new version a
975few minutes ago! Most users would immediately rush over to Gentoo's bugzilla to
976report the new version is available; please bump the existing version and add
977it to Portage, etc. However, this is exactly what you should <b>not</b> do.
978These kinds of requests are called zero-day (or 0-day) bump requests, as they're
979made the same day that a new version is released.
980</p>
981
982<impo>
983<b>Please wait <e>at least</e> 48 hours before reporting a new release on our
984bugzilla.</b> Also, you <e>must</e> check bugzilla before posting your request
985to make sure that someone else hasn't already reported it, or that the Gentoo
986maintainers haven't already dealt with the new version.
987</impo>
988
989<p>
990Why should you wait? First, it's quite rude to demand that Gentoo developers
991drop everything they're doing just to add a new release that came out 15 minutes
992ago. Your zero-day bump request could be marked as INVALID or LATER, as
993developers have plenty of pressing issues to keep them busy. Second, developers
994are usually aware of pending new releases well in advance of users, as they must
995follow upstream quite closely. They already know a new version is on its way.
996In many cases, they will have already opened a bug, or might even already added
997it in Portage as a masked package.
998</p>
999
1000<p>
1001Be smart when testing and requesting new versions of packages. Search bugzilla
1002before posting your bump request -- is there already a bug open? Have you synced
1003lately; is it already in Portage? Has it actually been released by upstream?
1004Basic common sense will go a long way, and will endear you to developers that
1005already have a lot to do. If it's been several days since release and you're
1006sure that there are no open requests for it (and that it's not in Portage), then
1007you can open up a new bug. Be sure to mention that it compiles and runs well on
1008your arch. Any other helpful information you provide is most welcome.
1009</p>
1010
1011<p>
1012Want to see the newest version of your favorite package in Portage? File smart
1013bugs.
956</p> 1014</p>
957 1015
958</body> 1016</body>
959</section> 1017</section>
960</chapter> 1018</chapter>
1099<p> 1157<p>
1100Please attach any file mentioned like this to your bug report. 1158Please attach any file mentioned like this to your bug report.
1101</p> 1159</p>
1102 1160
1103<p> 1161<p>
1104While we're doing all this, suppose another person finds your bug by searching 1162Sometimes a developer might ask you to attach a diff or patch for a file.
1105through bugzilla and is curious to keep track of the bug, they may do so by 1163Standard diff files can be obtained through:
1106putting their email in the Add CC field of the bug as shown below. You could 1164</p>
1165
1166<pre caption="Standard Diff Creation">
1167$ <i>cp file file.old</i>
1168$ <i>nano file</i>
1169$ <i>diff -u file.old file</i>
1170</pre>
1171
1172<p>
1173For C/C++ source files, the <b>-p</b> flag is added to show what function calls
1174the diff applies to:
1175</p>
1176
1177<pre caption="Diff-ing C/C++ source">
1178$ <i>cp file.c file.c.old</i>
1179$ <i>nano file.c</i>
1180$ <i>diff -up file.c.old file.c</i>
1181</pre>
1182
1183<p>
1184The documentation team will require the flag combination <b>-Nt</b> as well as
1185<b>-u</b>. This mainly has to do with tab expansion. You can create such a diff
1186with:
1187</p>
1188
1189<pre caption="Documentation diffs">
1190$<i> cp file.xml file.xml.old</i>
1191$<i> nano file.xml</i>
1192$<i> diff -Nut file.xml.old file.xml</i>
1193</pre>
1194
1195<p>
1196And your diff is created. While we're doing all this, suppose another person
1197finds your bug by searching through bugzilla and is curious to keep track of
1198the bug, they may do so by putting their email in the Add CC field of the bug
1107also keep track of other bugs by following the same method. 1199as shown below. You could also keep track of other bugs by following the same
1200method.
1108</p> 1201</p>
1109 1202
1110<figure link="/images/docs/bugzie-add-email.png" caption="Adding Email To CC:"/> 1203<figure link="/images/docs/bugzie-add-email.png" caption="Adding Email To CC:"/>
1111 1204
1112<note> 1205<note>
1247</pre> 1340</pre>
1248 1341
1249<p> 1342<p>
1250Now we'll want to create the appropriate directories to put our test ebuild 1343Now we'll want to create the appropriate directories to put our test ebuild
1251files in. In this case, we're supposed to put them in sys-apps/foobar2. You'll 1344files in. In this case, we're supposed to put them in sys-apps/foobar2. You'll
1252notice that the second comment asks for a files directory for the patch. The 1345notice that the second comment asks for a <path>files</path> directory for the
1253files directory holds the digests (md5sums of files for a particular version of 1346patch. This directory holds other required files that aren't included with
1254a package) and any other required files that aren't included with the standard
1255source archive (patches, init.d scripts, etc). This is a subdir in the package 1347the standard source archive (patches, init.d scripts, etc). This is a subdir in
1256directory called files. Go ahead and create these directories: 1348the package directory called <path>files</path>. Go ahead and create these
1349directories:
1257</p> 1350</p>
1258 1351
1259<pre caption="Setting Up The Category And Package Directories"> 1352<pre caption="Setting Up The Category And Package Directories">
1260# <i>mkdir -p /usr/local/portage/sys-apps/foobar2/files</i> 1353# <i>mkdir -p /usr/local/portage/sys-apps/foobar2/files</i>
1261</pre> 1354</pre>
1278<title>Testing The ebuild</title> 1371<title>Testing The ebuild</title>
1279<body> 1372<body>
1280 1373
1281<p> 1374<p>
1282The process to create an ebuild that can be used by emerge is fairly simple. You 1375The process to create an ebuild that can be used by emerge is fairly simple. You
1283must create a Manifest and a digest file for the ebuild. This can be done with 1376must create a Manifest file for the ebuild. This can be done with
1284the ebuild command. Run it as shown. 1377the ebuild command. Run it as shown.
1285</p> 1378</p>
1286 1379
1287<pre caption="Creating the Manifest and digest files"> 1380<pre caption="Creating the Manifest file">
1288# <i>ebuild foobar2-1.0.ebuild digest</i> 1381# <i>ebuild foobar2-1.0.ebuild manifest</i>
1289&gt;&gt;&gt; Generating digest file... 1382&gt;&gt;&gt; Creating Manifest for /usr/local/portage/sys-apps/foobar2
1290&lt;&lt;&lt; foobar2-1.0.tar.bz2
1291&gt;&gt;&gt; Generating manifest file...
1292&lt;&lt;&lt; foobar2-1.0.ebuild
1293&lt;&lt;&lt; files/digest-foobar2-1.0
1294&lt;&lt;&lt; files/foobar2-1.0-Makefile.patch
1295&gt;&gt;&gt; Computed message digests.
1296</pre> 1383</pre>
1297 1384
1298<p> 1385<p>
1299Now let's test to see if it works as it should. 1386Now let's test to see if it works as it should.
1300</p> 1387</p>

Legend:
Removed from v.1.6  
changed lines
  Added in v.1.12

  ViewVC Help
Powered by ViewVC 1.1.20