* [gentoo-doc-cvs] cvs commit: bugzilla-howto.xml
@ 2007-04-01 10:35 Josh Saddler
0 siblings, 0 replies; 24+ messages in thread
From: Josh Saddler @ 2007-04-01 10:35 UTC (permalink / raw
To: gentoo-doc-cvs
nightmorph 07/04/01 10:35:45
Modified: bugzilla-howto.xml
Log:
added a smarter way to do attachments and info, thanks to jakub for the suggestion, bug 172975
Revision Changes Path
1.10 xml/htdocs/doc/en/bugzilla-howto.xml
file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.10&view=markup
plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.10&content-type=text/plain
diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml?r1=1.9&r2=1.10
Index: bugzilla-howto.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- bugzilla-howto.xml 14 Feb 2007 21:30:15 -0000 1.9
+++ bugzilla-howto.xml 1 Apr 2007 10:35:45 -0000 1.10
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.9 2007/02/14 21:30:15 nightmorph Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.10 2007/04/01 10:35:45 nightmorph Exp $ -->
<guide link="/doc/en/bugzilla-howto.xml">
<title>Gentoo Bug Reporting Guide</title>
@@ -20,8 +20,8 @@
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>
-<version>1.8</version>
-<date>2007-02-14</date>
+<version>1.9</version>
+<date>2007-04-01</date>
<chapter>
<title>Introduction</title>
@@ -848,9 +848,11 @@
is.
</li>
<li>
- URL is optional and is used to point to errors on a site someplace
- (pastebin, etc.). However, doing it inside the bug allows the developers be
- able to reference to it at any time and is preferred.
+ URL is optional and is used to point to relevant information on another site
+ (upstream bugzilla, release notes on package homepage etc.). You should
+ never use URL to point to pastebins for error messages, logs, <c>emerge
+ --info</c> output, screenshots or similar information. Instead, these should
+ always be attached to the bug.
</li>
<li>
In the Summary, you should put the package category, name, and number.
--
gentoo-doc-cvs@gentoo.org mailing list
^ permalink raw reply [flat|nested] 24+ messages in thread* [gentoo-doc-cvs] cvs commit: bugzilla-howto.xml
@ 2008-05-23 20:42 Sven Vermeulen
0 siblings, 0 replies; 24+ messages in thread
From: Sven Vermeulen @ 2008-05-23 20:42 UTC (permalink / raw
To: gentoo-doc-cvs
swift 08/05/23 20:42:42
Modified: bugzilla-howto.xml
Log:
Coding style
Revision Changes Path
1.13 xml/htdocs/doc/en/bugzilla-howto.xml
file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.13&view=markup
plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.13&content-type=text/plain
diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml?r1=1.12&r2=1.13
Index: bugzilla-howto.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- bugzilla-howto.xml 1 Feb 2008 19:30:40 -0000 1.12
+++ bugzilla-howto.xml 23 May 2008 20:42:42 -0000 1.13
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.12 2008/02/01 19:30:40 jkt Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.13 2008/05/23 20:42:42 swift Exp $ -->
<guide link="/doc/en/bugzilla-howto.xml">
<title>Gentoo Bug Reporting Guide</title>
@@ -201,7 +201,7 @@
<note>
One can also debug with core dumps. These core files contain the same
-information that the program would produce when run with gdb. In order to debug
+information that the program would produce when run with gdb. In order to debug
with a core file with bad_code, you would run <c>gdb ./bad_code core</c> where
core is the name of the core file.
</note>
@@ -327,11 +327,11 @@
</pre>
<p>
-This ends the walk-through of <c>gdb</c>. Using <c>gdb</c>, we hope that you will
-be able to use it to create better bug reports. However, there are other types
-of errors that can cause a program to fail during run time. One of the other
-ways is through improper file access. We can find those using a nifty little
-tool called <c>strace</c>.
+This ends the walk-through of <c>gdb</c>. Using <c>gdb</c>, we hope that you
+will be able to use it to create better bug reports. However, there are other
+types of errors that can cause a program to fail during run time. One of the
+other ways is through improper file access. We can find those using a nifty
+little tool called <c>strace</c>.
</p>
</body>
@@ -350,9 +350,9 @@
tool called <c>strace</c> was created to help deal with this. <c>strace</c>
traces system calls (hence the name) which include calls that use the memory and
files. For our example, we're going to take a program foobar2. This is an
-updated version of foobar. However, during the change over to foobar2, you notice
-all your configurations are missing! In foobar version 1, you had it setup to
-say "foo", but now it's using the default "bar".
+updated version of foobar. However, during the change over to foobar2, you
+notice all your configurations are missing! In foobar version 1, you had it
+setup to say "foo", but now it's using the default "bar".
</p>
<pre caption="Foobar2 With an invalid configuration">
@@ -454,9 +454,9 @@
</pre>
<p>
-The program is compiling smoothly when it suddenly stops and presents an error message. This
-particular error can be split into 3 different sections, The compile messages, the build
-error, and the emerge error message as shown below.
+The program is compiling smoothly when it suddenly stops and presents an error
+message. This particular error can be split into 3 different sections, The
+compile messages, the build error, and the emerge error message as shown below.
</p>
<pre caption="Parts of the error">
@@ -658,8 +658,8 @@
</p>
<p>
-Comment is the important part. Use the comment field to list what appears to be a
-specific instance of the error. Basically, don't use anything like the
+Comment is the important part. Use the comment field to list what appears to be
+a specific instance of the error. Basically, don't use anything like the
beginning of the build error, find a line that's before it stating a true
error. Also, you'll want to filter out any punctuation to prevent bugzilla
from interpreting the results the comment the wrong way. Example from the xclass
@@ -772,9 +772,9 @@
<note>
We would rather see a bug whose product was not supposed to be Gentoo Linux but
has been filed under the same rather than seeing a bug which belongs the Gentoo
-Linux product and filed elsewhere. While neither is preferred, the former is more
-acceptable and understandable (except website bugs.. we might have an issue with
-that...).
+Linux product and filed elsewhere. While neither is preferred, the former is
+more acceptable and understandable (except website bugs.. we might have an issue
+with that...).
</note>
<p>
@@ -934,7 +934,7 @@
Minor - Your program crashes here and there with apparent workarounds.
</li>
<li>
- Normal - The default. If you're not sure leave it here unless it's a new
+ Normal - The default. If you're not sure leave it here unless it's a new
build or cosmetic change, then read below for more information.
</li>
<li>Trivial - Things such as a mispelled word or whitespace clean up. </li>
@@ -1182,7 +1182,7 @@
<p>
The documentation team will require the flag combination <b>-Nt</b> as well as
-<b>-u</b>. This mainly has to do with tab expansion. You can create such a diff
+<b>-u</b>. This mainly has to do with tab expansion. You can create such a diff
with:
</p>
@@ -1251,7 +1251,7 @@
Now shortly afterward, we find the error in the strace log and fix the bug and
mark it as RESOLVED FIXED and mention that there was a change in the location
of configuration files, and that I will update the ebuild with a warning about
-it. The bug now becomes resolved, and you are shown the following.
+it. The bug now becomes resolved, and you are shown the following.
</p>
<figure link="/images/docs/bugzie-reso.png" caption="Resolved Bug"/>
@@ -1282,7 +1282,7 @@
</li>
<li>
CANTFIX - Somehow the bug cannot be solved because of certain
- circumstances. These circumstances will be noted by the person taking the
+ circumstances. These circumstances will be noted by the person taking the
bug.
</li>
<li>
@@ -1303,7 +1303,7 @@
<p>
Sometimes, before the bug can be resolved, a developer may request that you
-test an updated ebulid. In the next chapter we'll take a look at testing
+test an updated ebulid. In the next chapter we'll take a look at testing
ebuilds.
</p>
@@ -1422,7 +1422,7 @@
<p>
In the first section we see that the emerge started off as it should. The second
section shows our patch being applied successfully by the "[ ok ]" status
-message to the right. The last section tells us the program compiled ok. The
+message to the right. The last section tells us the program compiled ok. The
patch works! Now we can go and let the developer know that their patch works
fine, and that they can commit the fix to portage.
</p>
--
gentoo-doc-cvs@lists.gentoo.org mailing list
^ permalink raw reply [flat|nested] 24+ messages in thread* [gentoo-doc-cvs] cvs commit: bugzilla-howto.xml
@ 2008-02-01 19:30 Jan Kundrat
0 siblings, 0 replies; 24+ messages in thread
From: Jan Kundrat @ 2008-02-01 19:30 UTC (permalink / raw
To: gentoo-doc-cvs
jkt 08/02/01 19:30:40
Modified: bugzilla-howto.xml
Log:
#208475, Manifests aren't under files/ directory
Also addedd some markup around "files".
Revision Changes Path
1.12 xml/htdocs/doc/en/bugzilla-howto.xml
file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.12&view=markup
plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.12&content-type=text/plain
diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml?r1=1.11&r2=1.12
Index: bugzilla-howto.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- bugzilla-howto.xml 31 Jan 2008 14:31:41 -0000 1.11
+++ bugzilla-howto.xml 1 Feb 2008 19:30:40 -0000 1.12
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.11 2008/01/31 14:31:41 jkt Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.12 2008/02/01 19:30:40 jkt Exp $ -->
<guide link="/doc/en/bugzilla-howto.xml">
<title>Gentoo Bug Reporting Guide</title>
@@ -20,7 +20,7 @@
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>
-<version>1.10</version>
+<version>1.11</version>
<date>2008-01-31</date>
<chapter>
@@ -1342,11 +1342,11 @@
<p>
Now we'll want to create the appropriate directories to put our test ebuild
files in. In this case, we're supposed to put them in sys-apps/foobar2. You'll
-notice that the second comment asks for a files directory for the patch. The
-files directory holds the Manifest files (md5sums of files for a particular version of
-a package) and any other required files that aren't included with the standard
-source archive (patches, init.d scripts, etc). This is a subdir in the package
-directory called files. Go ahead and create these directories:
+notice that the second comment asks for a <path>files</path> directory for the
+patch. This directory holds other required files that aren't included with
+the standard source archive (patches, init.d scripts, etc). This is a subdir in
+the package directory called <path>files</path>. Go ahead and create these
+directories:
</p>
<pre caption="Setting Up The Category And Package Directories">
--
gentoo-doc-cvs@lists.gentoo.org mailing list
^ permalink raw reply [flat|nested] 24+ messages in thread
* [gentoo-doc-cvs] cvs commit: bugzilla-howto.xml
@ 2008-01-31 21:33 Jan Kundrat
0 siblings, 0 replies; 24+ messages in thread
From: Jan Kundrat @ 2008-01-31 21:33 UTC (permalink / raw
To: gentoo-doc-cvs
jkt 08/01/31 21:33:54
Removed: bugzilla-howto.xml
Log:
The bugzilla guide has been living in xml/htdocs/doc/en/bugzilla-howto.xml for ages...
--
gentoo-doc-cvs@lists.gentoo.org mailing list
^ permalink raw reply [flat|nested] 24+ messages in thread
* [gentoo-doc-cvs] cvs commit: bugzilla-howto.xml
@ 2008-01-31 14:31 Jan Kundrat
0 siblings, 0 replies; 24+ messages in thread
From: Jan Kundrat @ 2008-01-31 14:31 UTC (permalink / raw
To: gentoo-doc-cvs
jkt 08/01/31 14:31:41
Modified: bugzilla-howto.xml
Log:
s/digest/Manifest/ and related fixes
Revision Changes Path
1.11 xml/htdocs/doc/en/bugzilla-howto.xml
file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.11&view=markup
plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.11&content-type=text/plain
diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml?r1=1.10&r2=1.11
Index: bugzilla-howto.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- bugzilla-howto.xml 1 Apr 2007 10:35:45 -0000 1.10
+++ bugzilla-howto.xml 31 Jan 2008 14:31:41 -0000 1.11
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.10 2007/04/01 10:35:45 nightmorph Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.11 2008/01/31 14:31:41 jkt Exp $ -->
<guide link="/doc/en/bugzilla-howto.xml">
<title>Gentoo Bug Reporting Guide</title>
@@ -20,8 +20,8 @@
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>
-<version>1.9</version>
-<date>2007-04-01</date>
+<version>1.10</version>
+<date>2008-01-31</date>
<chapter>
<title>Introduction</title>
@@ -1343,7 +1343,7 @@
Now we'll want to create the appropriate directories to put our test ebuild
files in. In this case, we're supposed to put them in sys-apps/foobar2. You'll
notice that the second comment asks for a files directory for the patch. The
-files directory holds the digests (md5sums of files for a particular version of
+files directory holds the Manifest files (md5sums of files for a particular version of
a package) and any other required files that aren't included with the standard
source archive (patches, init.d scripts, etc). This is a subdir in the package
directory called files. Go ahead and create these directories:
@@ -1373,19 +1373,13 @@
<p>
The process to create an ebuild that can be used by emerge is fairly simple. You
-must create a Manifest and a digest file for the ebuild. This can be done with
+must create a Manifest file for the ebuild. This can be done with
the ebuild command. Run it as shown.
</p>
-<pre caption="Creating the Manifest and digest files">
-# <i>ebuild foobar2-1.0.ebuild digest</i>
->>> Generating digest file...
-<<< foobar2-1.0.tar.bz2
->>> Generating manifest file...
-<<< foobar2-1.0.ebuild
-<<< files/digest-foobar2-1.0
-<<< files/foobar2-1.0-Makefile.patch
->>> Computed message digests.
+<pre caption="Creating the Manifest file">
+# <i>ebuild foobar2-1.0.ebuild manifest</i>
+>>> Creating Manifest for /usr/local/portage/sys-apps/foobar2
</pre>
<p>
--
gentoo-doc-cvs@lists.gentoo.org mailing list
^ permalink raw reply [flat|nested] 24+ messages in thread
* [gentoo-doc-cvs] cvs commit: bugzilla-howto.xml
@ 2007-02-14 21:30 Josh Saddler
0 siblings, 0 replies; 24+ messages in thread
From: Josh Saddler @ 2007-02-14 21:30 UTC (permalink / raw
To: gentoo-doc-cvs
nightmorph 07/02/14 21:30:16
Modified: bugzilla-howto.xml
Log:
added a section on zero-day bump requests to the bugzilla guide for bug 166809
Revision Changes Path
1.9 xml/htdocs/doc/en/bugzilla-howto.xml
file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.9&view=markup
plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.9&content-type=text/plain
diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml?r1=1.8&r2=1.9
Index: bugzilla-howto.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- bugzilla-howto.xml 10 Nov 2006 22:19:40 -0000 1.8
+++ bugzilla-howto.xml 14 Feb 2007 21:30:15 -0000 1.9
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.8 2006/11/10 22:19:40 nightmorph Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.9 2007/02/14 21:30:15 nightmorph Exp $ -->
<guide link="/doc/en/bugzilla-howto.xml">
<title>Gentoo Bug Reporting Guide</title>
@@ -20,8 +20,8 @@
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>
-<version>1.7</version>
-<date>2006-11-10</date>
+<version>1.8</version>
+<date>2007-02-14</date>
<chapter>
<title>Introduction</title>
@@ -958,6 +958,61 @@
</body>
</section>
+<section>
+<title>Zero-day bump requests</title>
+<body>
+
+<p>
+So far, we've shown what to do when filing a bug. Now let's take a look at what
+<e>not</e> to do.
+</p>
+
+<p>
+Suppose that you've eagerly been following an upstream project's schedule, and
+when you check their homepage, guess what? They just released a new version a
+few minutes ago! Most users would immediately rush over to Gentoo's bugzilla to
+report the new version is available; please bump the existing version and add
+it to Portage, etc. However, this is exactly what you should <b>not</b> do.
+These kinds of requests are called zero-day (or 0-day) bump requests, as they're
+made the same day that a new version is released.
+</p>
+
+<impo>
+<b>Please wait <e>at least</e> 48 hours before reporting a new release on our
+bugzilla.</b> Also, you <e>must</e> check bugzilla before posting your request
+to make sure that someone else hasn't already reported it, or that the Gentoo
+maintainers haven't already dealt with the new version.
+</impo>
+
+<p>
+Why should you wait? First, it's quite rude to demand that Gentoo developers
+drop everything they're doing just to add a new release that came out 15 minutes
+ago. Your zero-day bump request could be marked as INVALID or LATER, as
+developers have plenty of pressing issues to keep them busy. Second, developers
+are usually aware of pending new releases well in advance of users, as they must
+follow upstream quite closely. They already know a new version is on its way.
+In many cases, they will have already opened a bug, or might even already added
+it in Portage as a masked package.
+</p>
+
+<p>
+Be smart when testing and requesting new versions of packages. Search bugzilla
+before posting your bump request -- is there already a bug open? Have you synced
+lately; is it already in Portage? Has it actually been released by upstream?
+Basic common sense will go a long way, and will endear you to developers that
+already have a lot to do. If it's been several days since release and you're
+sure that there are no open requests for it (and that it's not in Portage), then
+you can open up a new bug. Be sure to mention that it compiles and runs well on
+your arch. Any other helpful information you provide is most welcome.
+</p>
+
+<p>
+Want to see the newest version of your favorite package in Portage? File smart
+bugs.
+</p>
+
+</body>
+</section>
</chapter>
<chapter>
--
gentoo-doc-cvs@gentoo.org mailing list
^ permalink raw reply [flat|nested] 24+ messages in thread
* [gentoo-doc-cvs] cvs commit: bugzilla-howto.xml
@ 2006-11-10 22:19 Josh Saddler
0 siblings, 0 replies; 24+ messages in thread
From: Josh Saddler @ 2006-11-10 22:19 UTC (permalink / raw
To: gentoo-doc-cvs
nightmorph 06/11/10 22:19:40
Modified: bugzilla-howto.xml
Log:
added link to gpm guide (copy & paste howto), thanks to diox for suggesting on IRC
Revision Changes Path
1.8 xml/htdocs/doc/en/bugzilla-howto.xml
file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.8&view=markup
plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.8&content-type=text/plain
diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml?r1=1.7&r2=1.8
Index: bugzilla-howto.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- bugzilla-howto.xml 2 Sep 2006 05:26:46 -0000 1.7
+++ bugzilla-howto.xml 10 Nov 2006 22:19:40 -0000 1.8
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.7 2006/09/02 05:26:46 rane Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.8 2006/11/10 22:19:40 nightmorph Exp $ -->
<guide link="/doc/en/bugzilla-howto.xml">
<title>Gentoo Bug Reporting Guide</title>
@@ -20,8 +20,8 @@
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>
-<version>1.6</version>
-<date>2006-09-01</date>
+<version>1.7</version>
+<date>2006-11-10</date>
<chapter>
<title>Introduction</title>
@@ -310,13 +310,14 @@
</pre>
<p>
-As you can see, -ggdb adds about <e>13178</e> more bytes to the file size over the one
-with debugging symbols. However, as shown above, this increase in file size can
-be worth it if presenting debug information to developers. The backtrace can be
-saved to a file by copying and pasting from the terminal (if it's a non-x based
-terminal, you can use gpm. To keep this doc simple, I recommend you read up on
-the documentation for gpm to see how to copy and paste with it). Now that we're
-done with <c>gdb</c>, we can quit.
+As you can see, -ggdb adds about <e>13178</e> more bytes to the file size over
+the one with debugging symbols. However, as shown above, this increase in file
+size can be worth it if presenting debug information to developers. The
+backtrace can be saved to a file by copying and pasting from the terminal (if
+it's a non-x based terminal, you can use gpm. To keep this doc simple, I
+recommend you read up on the <uri link="/doc/en/gpm.xml#doc_chap4">documentation
+for gpm</uri> to see how to copy and paste with it). Now that we're done with
+<c>gdb</c>, we can quit.
</p>
<pre caption="Quitting GDB">
--
gentoo-doc-cvs@gentoo.org mailing list
^ permalink raw reply [flat|nested] 24+ messages in thread
* [gentoo-doc-cvs] cvs commit: bugzilla-howto.xml
@ 2006-09-02 5:26 Lukasz Damentko
0 siblings, 0 replies; 24+ messages in thread
From: Lukasz Damentko @ 2006-09-02 5:26 UTC (permalink / raw
To: gentoo-doc-cvs
rane 06/09/02 05:26:46
Modified: bugzilla-howto.xml
Log:
#119053, added instructions about making diffs
Revision Changes Path
1.7 xml/htdocs/doc/en/bugzilla-howto.xml
file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.7&view=markup
plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.7&content-type=text/plain
diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml?r1=1.6&r2=1.7
Index: bugzilla-howto.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- bugzilla-howto.xml 30 Aug 2005 02:51:12 -0000 1.6
+++ bugzilla-howto.xml 2 Sep 2006 05:26:46 -0000 1.7
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.6 2005/08/30 02:51:12 vapier Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.7 2006/09/02 05:26:46 rane Exp $ -->
<guide link="/doc/en/bugzilla-howto.xml">
<title>Gentoo Bug Reporting Guide</title>
@@ -20,8 +20,8 @@
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>
-<version>1.5</version>
-<date>2005-08-29</date>
+<version>1.6</version>
+<date>2006-09-01</date>
<chapter>
<title>Introduction</title>
@@ -1101,10 +1101,45 @@
</p>
<p>
-While we're doing all this, suppose another person finds your bug by searching
-through bugzilla and is curious to keep track of the bug, they may do so by
-putting their email in the Add CC field of the bug as shown below. You could
-also keep track of other bugs by following the same method.
+Sometimes a developer might ask you to attach a diff or patch for a file.
+Standard diff files can be obtained through:
+</p>
+
+<pre caption="Standard Diff Creation">
+$ <i>cp file file.old</i>
+$ <i>nano file</i>
+$ <i>diff -u file.old file</i>
+</pre>
+
+<p>
+For C/C++ source files, the <b>-p</b> flag is added to show what function calls
+the diff applies to:
+</p>
+
+<pre caption="Diff-ing C/C++ source">
+$ <i>cp file.c file.c.old</i>
+$ <i>nano file.c</i>
+$ <i>diff -up file.c.old file.c</i>
+</pre>
+
+<p>
+The documentation team will require the flag combination <b>-Nt</b> as well as
+<b>-u</b>. This mainly has to do with tab expansion. You can create such a diff
+with:
+</p>
+
+<pre caption="Documentation diffs">
+$<i> cp file.xml file.xml.old</i>
+$<i> nano file.xml</i>
+$<i> diff -Nut file.xml.old file.xml</i>
+</pre>
+
+<p>
+And your diff is created. While we're doing all this, suppose another person
+finds your bug by searching through bugzilla and is curious to keep track of
+the bug, they may do so by putting their email in the Add CC field of the bug
+as shown below. You could also keep track of other bugs by following the same
+method.
</p>
<figure link="/images/docs/bugzie-add-email.png" caption="Adding Email To CC:"/>
--
gentoo-doc-cvs@gentoo.org mailing list
^ permalink raw reply [flat|nested] 24+ messages in thread
* [gentoo-doc-cvs] cvs commit: bugzilla-howto.xml
@ 2005-09-29 15:11 Xavier Neys
0 siblings, 0 replies; 24+ messages in thread
From: Xavier Neys @ 2005-09-29 15:11 UTC (permalink / raw
To: gentoo-doc-cvs
neysx 05/09/29 15:11:35
Modified: xml/htdocs/doc/en/draft bugzilla-howto.xml
debugging-howto.xml ldapdns-guide.xml pax-utils.xml
pocketpc-guide.xml vpnc-howto.xml
Log:
Fixed links
Revision Changes Path
1.10 +8 -8 xml/htdocs/doc/en/draft/bugzilla-howto.xml
file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/bugzilla-howto.xml?rev=1.10&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/bugzilla-howto.xml?rev=1.10&content-type=text/plain&cvsroot=gentoo
diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/bugzilla-howto.xml.diff?r1=1.9&r2=1.10&cvsroot=gentoo
Index: bugzilla-howto.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/bugzilla-howto.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- bugzilla-howto.xml 13 Jul 2005 05:48:11 -0000 1.9
+++ bugzilla-howto.xml 29 Sep 2005 15:11:35 -0000 1.10
@@ -1,8 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/bugzilla-howto.xml,v 1.9 2005/07/13 05:48:11 fox2mike Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/bugzilla-howto.xml,v 1.10 2005/09/29 15:11:35 neysx Exp $ -->
-<guide link="/doc/en/bugzilla-howto.xml">
+<guide link="/doc/en/draft/bugzilla-howto.xml">
<title>Gentoo Bug Reporting Guide</title>
<author title="Author">
@@ -108,7 +108,7 @@
<p>
This is how the Advanced Search Page looks like. While it may seem overwhelming
at first, we're going to look at a few simple areas to narrow down the rather
-vague searches bugzilla returns.
+vague searches bugzilla returns.
</p>
<figure link="/images/docs/bugzie-content.png" caption="Content"/>
@@ -229,11 +229,11 @@
<p>
Another common misconception occurs with our Documentation bugs. For example, a
user finds a bug with the <uri
-link="http://www.gentoo.org/proj/en/releng/catalyst/index.xml">Catalyst
+link="/proj/en/releng/catalyst/index.xml">Catalyst
Docs</uri>. The general tendency is to file a bug under Docs-user, which gets
assigned to the <uri link="http://gdp.gentoo.org">GDP</uri>, when it should
actually go to a member of the <uri
-link="http://www.gentoo.org/proj/en/releng/">Release Engineering</uri> team. As
+link="/proj/en/releng/">Release Engineering</uri> team. As
a rule of thumb, only documentation under http://www.gentoo.org/doc/* is under
the GDP. Anything under http://www.gentoo.org/proj/* is under the respective
teams.
@@ -328,7 +328,7 @@
reference to it at any time and is preferred.
</li>
<li>
- In the Summary, you should put the package category, name, and number.
+ In the Summary, you should put the package category, name, and number.
</li>
</ul>
@@ -524,7 +524,7 @@
We'll just enter strace.log here, since that's quite self-explanatory.
</li>
<li>
- Content Type - This is the type of the file we're attaching to the bug.
+ Content Type - This is the type of the file we're attaching to the bug.
</li>
<li>
Obsoletes - If there were attachements submitted to the bug before the current
@@ -637,7 +637,7 @@
Now shortly afterward, we find the error in the strace log and fix the bug and
mark it as RESOLVED FIXED and mention that there was a change in the location of
configuration files, and that I will update the ebuild with a warning about it.
-The bug now becomes resolved, and you are shown the following.
+The bug now becomes resolved, and you are shown the following.
</p>
<figure link="/images/docs/bugzie-reso.png" caption="Resolved Bug"/>
1.5 +26 -26 xml/htdocs/doc/en/draft/debugging-howto.xml
file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/debugging-howto.xml?rev=1.5&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/debugging-howto.xml?rev=1.5&content-type=text/plain&cvsroot=gentoo
diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/debugging-howto.xml.diff?r1=1.4&r2=1.5&cvsroot=gentoo
Index: debugging-howto.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/debugging-howto.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- debugging-howto.xml 14 Jul 2005 09:54:37 -0000 1.4
+++ debugging-howto.xml 29 Sep 2005 15:11:35 -0000 1.5
@@ -1,8 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/debugging-howto.xml,v 1.4 2005/07/14 09:54:37 fox2mike Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/debugging-howto.xml,v 1.5 2005/09/29 15:11:35 neysx Exp $ -->
-<guide link="/doc/en/debugging-howto.xml">
+<guide link="/doc/en/draft/debugging-howto.xml">
<title>Gentoo Linux Debugging Guide</title>
<author title="Author">
@@ -90,7 +90,7 @@
These errors can be quite troublesome. However, once you find them, what do
you do? The following sections will look at two important tools for handling
run time errors. After that, we'll take a look at compile errors, and how to
-handle them. Let's start out with the first tool for debugging run time
+handle them. Let's start out with the first tool for debugging run time
errors -- <c>gdb</c>.
</p>
@@ -112,7 +112,7 @@
program is to <c>emerge</c> the program with <c>FEATURES="nostrip"</c>. This
prevents the stripping of debug symbols. Why are programs stripped by default?
The reason is the same as that for having gzipped man pages -- saving space.
-Here's how the size of a program varies with and without debug symbol stripping.
+Here's how the size of a program varies with and without debug symbol stripping.
</p>
<pre caption="Filesize Comparison">
@@ -129,7 +129,7 @@
the size! Two more things can be done for debugging. The first is adding ggdb3
to your CFLAGS and CXXFLAGS. This flag adds more debugging information than is
generally included. We'll see what that means later on. This is how
-<path>/etc/make.conf</path> <e>might</e> look with the newly added flags.
+<path>/etc/make.conf</path> <e>might</e> look with the newly added flags.
</p>
<pre caption="make.conf settings">
@@ -138,9 +138,9 @@
</pre>
<p>
-Lastly, you can also add debug to the package's USE flags. This can be done
+Lastly, you can also add debug to the package's USE flags. This can be done
with the <path>package.use</path> file.
-</p>
+</p>
<pre caption="Using package.use to add debug USE flag">
# <i>echo "category/package debug" >> /etc/portage/package.use</i>
@@ -245,7 +245,7 @@
run_it(), and somewhere in run_it() lies the strcpy() at fault. Things such as
this help developers narrow down problems. There are a few exceptions to the
output. First off is forgetting to enable debug symbols with
-<c>FEATURES="nostrip"</c>. With debug symbols stripped, the output looks
+<c>FEATURES="nostrip"</c>. With debug symbols stripped, the output looks
something like this:
</p>
@@ -311,13 +311,13 @@
</pre>
<p>
-As you can see, -ggdb3 adds about <e>13178</e> more bytes to the file size
-over the one with debugging symbols. However, as shown above, this increase
+As you can see, -ggdb3 adds about <e>13178</e> more bytes to the file size
+over the one with debugging symbols. However, as shown above, this increase
in file size can be worth it if presenting debug information to developers.
-The backtrace can be saved to a file by copying and pasting from the
-terminal (if it's a non-x based terminal, you can use gpm. To keep this
+The backtrace can be saved to a file by copying and pasting from the
+terminal (if it's a non-x based terminal, you can use gpm. To keep this
doc simple, I recommend you read up on the documentation for gpm to see
-how to copy and paste with it). Now that we're done with <c>gdb</c>, we
+how to copy and paste with it). Now that we're done with <c>gdb</c>, we
can quit.
</p>
@@ -328,10 +328,10 @@
</pre>
<p>
-This ends the walk-through of <c>gdb</c>. Using <c>gdb</c>, we hope that you
-will be able to use it to create better bug reports. However, there are other
-types of errors that can cause a program to fail during run time. One of the
-other ways is through improper file access. We can find those using a nifty
+This ends the walk-through of <c>gdb</c>. Using <c>gdb</c>, we hope that you
+will be able to use it to create better bug reports. However, there are other
+types of errors that can cause a program to fail during run time. One of the
+other ways is through improper file access. We can find those using a nifty
little tool called <c>strace</c>.
</p>
@@ -351,8 +351,8 @@
tool called <c>strace</c> was created to help deal with this. <c>strace</c>
traces system calls (hence the name) which include calls that use the memory and
files. For our example, we're going to take a program foobar2. This is an
-updated version of foobar. However, during the change over to foobar2, you
-notice all your configurations are missing! In foobar version 1, you had it
+updated version of foobar. However, during the change over to foobar2, you
+notice all your configurations are missing! In foobar version 1, you had it
setup to say "foo", but now it's using the default "bar".
</p>
@@ -397,7 +397,7 @@
reading in "bar" as it should. In this case, we can recommend the ebuild
maintainer to put a warning about it. For now though, we can copy over the
config file from <path>.foobar</path> and modify it to produce the correct
-results.
+results.
</p>
</body>
@@ -407,7 +407,7 @@
<body>
<p>
-<c>strace</c> is a great way at seeing what the kernel is doing to with the
+<c>strace</c> is a great way at seeing what the kernel is doing to with the
filesystem. Another program exists to help users see what the kernel is doing,
and help with kernel debugging. This program is called <c>dmesg</c>.
</p>
@@ -459,7 +459,7 @@
hdc: ATAPI 48X DVD-ROM drive, 512kB Cache, UDMA(33)
ide-floppy driver 0.99.newide
libata version 1.11 loaded.
-usbmon: debugs is not available
+usbmon: debugs is not available
</pre>
<p>
@@ -571,8 +571,8 @@
</pre>
<p>
-The program is compiling smoothly when it suddenly stops and presents an error
-message. This particular error can be split into 3 different sections, The
+The program is compiling smoothly when it suddenly stops and presents an error
+message. This particular error can be split into 3 different sections, The
compile messages, the build error, and the emerge error message as shown below.
</p>
@@ -628,7 +628,7 @@
<body>
<p>
-PORT_LOGDIR is a portage variable that sets up a log directory for separate
+PORT_LOGDIR is a portage variable that sets up a log directory for separate
emerge logs. Let's take a look and see what that entails. First, run your emerge
with PORT_LOGDIR set to your favorite log location. Let's say we have a
location <path>/var/log/portage</path>. We'll use that for our log directory:
@@ -665,7 +665,7 @@
on as we'll see in the bug reporting section. Now that we've safely obtained
our information needed to report the bug we can continue to do so. However,
before we get started on that, we need to make sure no one else has reported
-the issue.
+the issue.
</p>
</body>
1.3 +6 -6 xml/htdocs/doc/en/draft/ldapdns-guide.xml
file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/ldapdns-guide.xml?rev=1.3&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/ldapdns-guide.xml?rev=1.3&content-type=text/plain&cvsroot=gentoo
diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/ldapdns-guide.xml.diff?r1=1.2&r2=1.3&cvsroot=gentoo
Index: ldapdns-guide.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/ldapdns-guide.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ldapdns-guide.xml 20 Sep 2005 18:26:03 -0000 1.2
+++ ldapdns-guide.xml 29 Sep 2005 15:11:35 -0000 1.3
@@ -1,6 +1,6 @@
<?xml version='1.0' encoding="UTF-8"?>
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/ldapdns-guide.xml,v 1.2 2005/09/20 18:26:03 swift Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/ldapdns-guide.xml,v 1.3 2005/09/29 15:11:35 neysx Exp $ -->
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
@@ -44,7 +44,7 @@
simply explained, a line that contains the mapping between a hostname and an IP
address). LDAP is a standard protocol to obtain information from a
hierarchically represented knowledge base (directories). The most well-known
-LDAP service for Linux is OpenLDAP, a free LDAP implementation.
+LDAP service for Linux is OpenLDAP, a free LDAP implementation.
</p>
<p>
@@ -62,7 +62,7 @@
<body>
<p>
-First, install <c>net-dns/ldapdns</c>.
+First, install <c>net-dns/ldapdns</c>.
</p>
<pre caption="Installing ldapdns">
@@ -122,7 +122,7 @@
</table>
<p>
-You should substitute the <c>127.0.0.1</c> IP address with an IP address that
+You should substitute the <c>127.0.0.1</c> IP address with an IP address that
all hosts can reach and don't forget to use the domain name you want instead of
<c>yourdomain</c>.
</p>
@@ -193,11 +193,11 @@
<p>
Bootstrap LDAP with the base dn you defined previously with <c>ldapdns-conf</c>.
To accomplish this, we first create a file called <path>bootstrap.ldif</path>
-(it is just a name) which we fill up with DNS information.
+(it is just a name) which we fill up with DNS information.
</p>
<p>
-As an example, we provide a <uri link="bootstrap.ldif.txt">bootstrap.ldif</uri>
+As an example, we provide a <uri link="bootstrap.ldif.txt">bootstrap.ldif</uri>
file for a fictuous domain <c>cherchetoujours.org</c>.
</p>
1.2 +2 -2 xml/htdocs/doc/en/draft/pax-utils.xml
file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/pax-utils.xml?rev=1.2&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/pax-utils.xml?rev=1.2&content-type=text/plain&cvsroot=gentoo
diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/pax-utils.xml.diff?r1=1.1&r2=1.2&cvsroot=gentoo
Index: pax-utils.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/pax-utils.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- pax-utils.xml 28 Jun 2005 11:42:43 -0000 1.1
+++ pax-utils.xml 29 Sep 2005 15:11:35 -0000 1.2
@@ -1,10 +1,10 @@
<?xml version='1.0' encoding="UTF-8"?>
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/pax-utils.xml,v 1.1 2005/06/28 11:42:43 swift Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/pax-utils.xml,v 1.2 2005/09/29 15:11:35 neysx Exp $ -->
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
-<guide link="/doc/en/handbook/draft/pax-utils.xml">
+<guide link="/doc/en/draft/pax-utils.xml">
<title>Gentoo PaX Utilities</title>
<author title="Author">
1.2 +41 -41 xml/htdocs/doc/en/draft/pocketpc-guide.xml
file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/pocketpc-guide.xml?rev=1.2&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/pocketpc-guide.xml?rev=1.2&content-type=text/plain&cvsroot=gentoo
diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/pocketpc-guide.xml.diff?r1=1.1&r2=1.2&cvsroot=gentoo
Index: pocketpc-guide.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/pocketpc-guide.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- pocketpc-guide.xml 30 Aug 2005 09:04:28 -0000 1.1
+++ pocketpc-guide.xml 29 Sep 2005 15:11:35 -0000 1.2
@@ -1,8 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE guide SYSTEM "http://www.gentoo.org/dtd/guide.dtd">
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/pocketpc-guide.xml,v 1.1 2005/08/30 09:04:28 fox2mike Exp $ -->
+<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/pocketpc-guide.xml,v 1.2 2005/09/29 15:11:35 neysx Exp $ -->
-<guide link="/doc/en/pocketpc-guide.xml">
+<guide link="/doc/en/draft/pocketpc-guide.xml">
<title>Working with Pocket PCs using libsynCE</title>
<author title="Author">
@@ -37,9 +37,9 @@
</p>
<p>
-The first thing we need to do is get the kernel to recognize our device. In
+The first thing we need to do is get the kernel to recognize our device. In
this case, we have an HP iPAQ 1945. It is usb based and the module needed is
-called <c>ipaq</c>.
+called <c>ipaq</c>.
</p>
<pre caption="iPAQ Kernel Config">
@@ -66,11 +66,11 @@
<body>
<p>
-Ok, now that we have the kernel module setup, let's go ahead and get some
-information. Before we begin though, allow me to explain something. While it
-states USB Serial Converter, it's basically taking your PDA and communicating
-using serial over USB. That means this device is a USB based IPAQ. In fact,
-we even use ppp later on to create the connection. First though, let's plugin
+Ok, now that we have the kernel module setup, let's go ahead and get some
+information. Before we begin though, allow me to explain something. While it
+states USB Serial Converter, it's basically taking your PDA and communicating
+using serial over USB. That means this device is a USB based IPAQ. In fact,
+we even use ppp later on to create the connection. First though, let's plugin
our device and take a look at our modules list (note this is a udev system):
</p>
@@ -94,11 +94,11 @@
</pre>
<p>
-In the first code segment, we see that as soon as the ipaq is plugged in, the
-ipaq module is loaded (this is with coldplug of course). Not only that, but a
-quick scan of dmesg shows that our setup works, and that the device is now
-located at /dev/tts/USB0. Remember this, as we'll need it for configuration
-later on. Now that we have our device setup, let's get ahold of some packages
+In the first code segment, we see that as soon as the ipaq is plugged in, the
+ipaq module is loaded (this is with coldplug of course). Not only that, but a
+quick scan of dmesg shows that our setup works, and that the device is now
+located at /dev/tts/USB0. Remember this, as we'll need it for configuration
+later on. Now that we have our device setup, let's get ahold of some packages
that will help us communicate with it.
</p>
@@ -113,8 +113,8 @@
<body>
<p>
-Alright, the first thing we need to do is get ahold of the tools that will
-allow us to communicate with the PocketPC. So, we'll need to get ahold of the
+Alright, the first thing we need to do is get ahold of the tools that will
+allow us to communicate with the PocketPC. So, we'll need to get ahold of the
following packages:
</p>
@@ -140,7 +140,7 @@
<p>
Alright, remember that device node I told you we'd need. Here's where it comes
into play. Now, as part of the synce-serial package, we have something called
-synce-serial-config. This is what we'll use to configure the device. To do
+synce-serial-config. This is what we'll use to configure the device. To do
so, simply give it the device node from earlier:
</p>
@@ -151,8 +151,8 @@
</pre>
<p>
-Please note that when you feed synce-serial-config the device node, do it
-without the /dev. Now that we have it up and running, we can begin to use the
+Please note that when you feed synce-serial-config the device node, do it
+without the /dev. Now that we have it up and running, we can begin to use the
device.
</p>
@@ -167,9 +167,9 @@
<body>
<p>
-In order to use the IPAQ, we need to run a couple of commands. The first is
-dccm. This is our connection manager for the ipaq, and without it programs
-won't be able to connect. To use this run it <e>AS THE USER WHO WILL ACCESS
+In order to use the IPAQ, we need to run a couple of commands. The first is
+dccm. This is our connection manager for the ipaq, and without it programs
+won't be able to connect. To use this run it <e>AS THE USER WHO WILL ACCESS
SYNCE APPS</e>. So we do as so:
</p>
@@ -180,7 +180,7 @@
</pre>
<p>
-Now one more quick bit of user switching again, and we will now initiate the
+Now one more quick bit of user switching again, and we will now initiate the
connection with the device:
</p>
@@ -191,8 +191,8 @@
</pre>
<p>
-Your device should now respond to the connection. Mine does by displaying the
-sync icon and beeping to announce the connection. Now let's start by working
+Your device should now respond to the connection. Mine does by displaying the
+sync icon and beeping to announce the connection. Now let's start by working
with files.
</p>
@@ -208,15 +208,15 @@
<pre caption="IPAQ structure">
My Device
- - My Documents
- - Program Files
- - Storage Card
- - Temp
- - Windows
+ - My Documents
+ - Program Files
+ - Storage Card
+ - Temp
+ - Windows
</pre>
<p>
-Now let's see how we can copy files over. To accomplish this, we use the tools
+Now let's see how we can copy files over. To accomplish this, we use the tools
that come with synce:
</p>
@@ -278,8 +278,8 @@
</pre>
<p>
-There we go, we have all the information about the IPAQ, which means our
-connection was successful. Now let's try to copy some files over. We use the
+There we go, we have all the information about the IPAQ, which means our
+connection was successful. Now let's try to copy some files over. We use the
pcp program for this. First, we'll copy a file "test.txt" over to the IPAQ:
</p>
@@ -289,9 +289,9 @@
</pre>
<p>
-A small note, the ':' indicates the IPAQ is the destination. Also, the IPAQ
-defaults to My Documents when you open File Explorer. However, the file is
-copied to My Device instead. If you wanted to copy it to My Documents, you
+A small note, the ':' indicates the IPAQ is the destination. Also, the IPAQ
+defaults to My Documents when you open File Explorer. However, the file is
+copied to My Device instead. If you wanted to copy it to My Documents, you
would do as such:
</p>
@@ -314,9 +314,9 @@
</pre>
<p>
-In this case, it accesses the My Documents folder, not My Device. Remember
-that when you copy over! As a final example, the IPAQ has the ability to play
-MP3's, but only with a storage card. Let's take a small folder full of mp3's
+In this case, it accesses the My Documents folder, not My Device. Remember
+that when you copy over! As a final example, the IPAQ has the ability to play
+MP3's, but only with a storage card. Let's take a small folder full of mp3's
and copy them over to the storage card (Remember, the storage card is displayed
as Storage Card in the IPAQ):
</p>
@@ -340,7 +340,7 @@
<body>
<p>
-I hope this tutorial works out for you ok. If you have any inquiries about
+I hope this tutorial works out for you ok. If you have any inquiries about
this article, please email me at <mail>chriswhite@gentoo.org</mail>.
</p>
1.3 +54 -54 xml/htdocs/doc/en/draft/vpnc-howto.xml
file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/vpnc-howto.xml?rev=1.3&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/vpnc-howto.xml?rev=1.3&content-type=text/plain&cvsroot=gentoo
diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/vpnc-howto.xml.diff?r1=1.2&r2=1.3&cvsroot=gentoo
Index: vpnc-howto.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/vpnc-howto.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- vpnc-howto.xml 7 Aug 2005 20:15:28 -0000 1.2
+++ vpnc-howto.xml 29 Sep 2005 15:11:35 -0000 1.3
@@ -9,7 +9,7 @@
David H. Askew
</author>
-<!--
+<!--
My email address is dhaskew on earthlink.net
-->
@@ -153,7 +153,7 @@
</pre>
<p>
-If you build TUN/TAP support as a module, you first must load the <c>tun</c>
+If you build TUN/TAP support as a module, you first must load the <c>tun</c>
module:
</p>
@@ -166,7 +166,7 @@
</pre>
<p>
-Now that the <c>tun</c> module is loaded, check <c>dmesg</c> output. You
+Now that the <c>tun</c> module is loaded, check <c>dmesg</c> output. You
should see something like the following:
</p>
@@ -185,7 +185,7 @@
<body>
<p>
-Now that you have a working kernel setup, you need to install
+Now that you have a working kernel setup, you need to install
<c>net-misc/vpnc</c>:
</p>
@@ -209,7 +209,7 @@
255.255.255.0 network. The LAN in question is run by a Gentoo box using an
iptables firewall, DHCP, caching DNS, etc ... and it masquerades the LAN
behind the public IP address it receives from an ISP. You also have a
-workstation on the LAN from which you want to be able to VPN into your
+workstation on the LAN from which you want to be able to VPN into your
office with.
</p>
@@ -272,9 +272,9 @@
discuss the basics of setting up vpnc. The configuration file for vpnc
connection settings can be located in a couple places, depending on how many
profiles you want to setup. By default, vpnc looks first for
-<path>/etc/vpnc/default.conf</path> for its connection settings. If it doesn't
+<path>/etc/vpnc/default.conf</path> for its connection settings. If it doesn't
find that file, then it looks for <path>/etc/vpnc.conf</path>. This setup will
-only address a single profile example and will use the configuration file
+only address a single profile example and will use the configuration file
location <path>/etc/vpnc.conf</path>. Make sure you do not have a
<path>/etc/vpnc/default.conf</path> file.
</p>
@@ -289,20 +289,20 @@
</pre>
<p>
-The configuration file example above should be modified to reflect the
-appropriate values for your setup. The gateway option
-<c>vpngateway.domain.org</c> can be a fully qualified domain name or an IP
-address. The ID and secret options should be given to you by a network
-administrator. If they are hesitant about giving you this info and you
-currently have a working setup on a Windows box which utilizes the official
-Cisco VPN client, then all you have to do is export your profile. The
+The configuration file example above should be modified to reflect the
+appropriate values for your setup. The gateway option
+<c>vpngateway.domain.org</c> can be a fully qualified domain name or an IP
+address. The ID and secret options should be given to you by a network
+administrator. If they are hesitant about giving you this info and you
+currently have a working setup on a Windows box which utilizes the official
+Cisco VPN client, then all you have to do is export your profile. The
user name and password options are for your normal network
sign-on, such as a Windows NT domain account.
</p>
<p>
If you are forced to export your profile from a Windows machine, then what you
-will likely have is a file ending in <path>.pcf</path>. This file will have
+will likely have is a file ending in <path>.pcf</path>. This file will have
all the information you need. Below is an example:
</p>
@@ -347,19 +347,19 @@
</pre>
<p>
-In the above example, we can see entries for <c>Host</c>, <c>GroupName</c> and
-<c>enc_GroupPwd</c>. Your <c>Username</c> and <c>UserPassword</c> may or may
+In the above example, we can see entries for <c>Host</c>, <c>GroupName</c> and
+<c>enc_GroupPwd</c>. Your <c>Username</c> and <c>UserPassword</c> may or may
not be exported depending on the setup.
</p>
<note>
-The vpnc configuration file uses an unencrypted group password (IPSec secret),
-so if you do not know the group password, but you have a copy of the encrypted
-group password from an exported profile, then you need not worry. The encoding
-scheme for these group passwords is widely known, and all you have to do is
-visit a web page that will offer to decrypt it for you. The
+The vpnc configuration file uses an unencrypted group password (IPSec secret),
+so if you do not know the group password, but you have a copy of the encrypted
+group password from an exported profile, then you need not worry. The encoding
+scheme for these group passwords is widely known, and all you have to do is
+visit a web page that will offer to decrypt it for you. The
<uri link="http://www.unix-ag.uni-kl.de/~massar/vpnc/">vpnc homepage</uri>
-has <uri link="http://www.unix-ag.uni-kl.de/~massar/bin/cisco-decode">a
+has <uri link="http://www.unix-ag.uni-kl.de/~massar/bin/cisco-decode">a
link</uri> to such a page.
</note>
@@ -376,14 +376,14 @@
<pre caption="Example vpnc-connect usage">
# <i>vpnc-connect</i>
-Enter password for username@vpngateway.domain.org:
+Enter password for username@vpngateway.domain.org:
VPNC started in background (pid: 14788)...
</pre>
<p>
As you can see from the above command output, once you type <c>vpnc-connect</c>
-(as root), you are prompted for your password. After entering your password,
-which will not be echoed back to you, the vpnc process will automatically
+(as root), you are prompted for your password. After entering your password,
+which will not be echoed back to you, the vpnc process will automatically
become a background process.
</p>
@@ -449,11 +449,11 @@
<p>
At this point, your workstation is capable of communicating with hosts via the
VPN, but only by IP address. As you might have noticed, vpnc did not alter
-your <path>/etc/resolv.conf</path>, thus not setting up DNS services for the
+your <path>/etc/resolv.conf</path>, thus not setting up DNS services for the
virtual link. Also, because vpnc sets your default route to your VPN gateway,
-all network traffic will travel across the VPN, even if it destined for the
-Internet or elsewhere not specifically specified by additional routes. For
-some, this basic type of connection may be satisfactory, but for most,
+all network traffic will travel across the VPN, even if it destined for the
+Internet or elsewhere not specifically specified by additional routes. For
+some, this basic type of connection may be satisfactory, but for most,
additional steps need to be taken.
</p>
@@ -465,7 +465,7 @@
<li>DNS for the VPN</li>
<li>
A routing setup that will only send traffic destined for the VPN down
- the virtual tunnel. This way, you can browse the Internet while connected
+ the virtual tunnel. This way, you can browse the Internet while connected
to the VPN, without your personal web/p2p etc ... traffic going across the
tunnel.
</li>
@@ -507,7 +507,7 @@
the traffic is destined for your VPN tunnel. This is a very functional solution
and if you simply need to connect to the tunnel, do your work, and then
disconnect, read no further. But, if you want to be able to leave your tunnel
-connected for lengthy periods of time and don't want your work DNS servers
+connected for lengthy periods of time and don't want your work DNS servers
handling requests for your personal traffic, read on.
</p>
@@ -520,12 +520,12 @@
</p>
<note>
-We will consider VPN-related DNS queries to be any query belonging to the
+We will consider VPN-related DNS queries to be any query belonging to the
example.org domain, such as host1.example.org or server1.example.org.
</note>
<p>
-So how do you set things up, so that only requests made to hosts on the
+So how do you set things up, so that only requests made to hosts on the
example.org domain get sent to VPN supplied DNS servers? Well, you're going to
need to install a local DNS server, but don't worry, it's much easier than you
think. There are several software packages that can handle the type of setup
@@ -543,9 +543,9 @@
</pre>
<p>
-Now you need to add an option to your <c>dnsmasq</c> startup options. Edit the
-following option to suit your needs. Substitute .example.org with the
-appropriate domain and the IP address with a valid DNS server that belongs
+Now you need to add an option to your <c>dnsmasq</c> startup options. Edit the
+following option to suit your needs. Substitute .example.org with the
+appropriate domain and the IP address with a valid DNS server that belongs
--
gentoo-doc-cvs@gentoo.org mailing list
^ permalink raw reply [flat|nested] 24+ messages in thread* [gentoo-doc-cvs] cvs commit: bugzilla-howto.xml
@ 2005-08-30 2:51 vapier
0 siblings, 0 replies; 24+ messages in thread
From: vapier @ 2005-08-30 2:51 UTC (permalink / raw
To: gentoo-doc-cvs
vapier 05/08/30 02:51:12
Modified: xml/htdocs/doc/en bugzilla-howto.xml
Log:
tell users to utilize -ggdb -g instead of -ggdb3 since -ggdb3 can cause problems itself and -ggdb/-g is sufficient most of the time
Revision Changes Path
1.6 +9 -9 xml/htdocs/doc/en/bugzilla-howto.xml
file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.6&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.6&content-type=text/plain&cvsroot=gentoo
diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/bugzilla-howto.xml.diff?r1=1.5&r2=1.6&cvsroot=gentoo
Index: bugzilla-howto.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- bugzilla-howto.xml 22 Jul 2005 23:46:11 -0000 1.5
+++ bugzilla-howto.xml 30 Aug 2005 02:51:12 -0000 1.6
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.5 2005/07/22 23:46:11 neysx Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.6 2005/08/30 02:51:12 vapier Exp $ -->
<guide link="/doc/en/bugzilla-howto.xml">
<title>Gentoo Bug Reporting Guide</title>
@@ -20,8 +20,8 @@
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>
-<version>1.4</version>
-<date>2005-07-22</date>
+<version>1.5</version>
+<date>2005-08-29</date>
<chapter>
<title>Introduction</title>
@@ -132,7 +132,7 @@
</p>
<pre caption="make.conf settings">
-CFLAGS="-O2 -pipe -ggdb3"
+CFLAGS="-O1 -pipe -g -ggdb"
CXXFLAGS="${CFLAGS}"
</pre>
@@ -281,7 +281,7 @@
This backtrace contains a large number of ?? marks. This is because without
debug symbols, <c>gdb</c> doesn't know how the program was run. Hence, it is
crucial that debug symbols are <e>not</e> stripped. Now remember a while ago we
-mentioned the -ggdb3 flag. Let's see what the output looks like with the flag
+mentioned the -ggdb flag. Let's see what the output looks like with the flag
enabled:
</p>
@@ -296,21 +296,21 @@
Here we see that a lot more information is available for developers. Not only is
function information displayed, but even the exact line numbers of the source
files. This method is the most preferred if you can spare the extra space.
-Here's how much the file size varies between debug, strip, and -ggdb3 enabled
+Here's how much the file size varies between debug, strip, and -ggdb enabled
programs.
</p>
-<pre caption="Filesize differences With -ggdb3 flag">
+<pre caption="Filesize differences With -ggdb flag">
<comment>(debug symbols stripped)</comment>
-rwxr-xr-x 1 chris users 3140 6/28 13:11 bad_code
<comment>(debug symbols enabled)</comment>
-rwxr-xr-x 1 chris users 6374 6/28 13:10 bad_code
-<comment>(-ggdb3 flag enabled)</comment>
+<comment>(-ggdb flag enabled)</comment>
-rwxr-xr-x 1 chris users 19552 6/28 13:11 bad_code
</pre>
<p>
-As you can see, -ggdb3 adds about <e>13178</e> more bytes to the file size over the one
+As you can see, -ggdb adds about <e>13178</e> more bytes to the file size over the one
with debugging symbols. However, as shown above, this increase in file size can
be worth it if presenting debug information to developers. The backtrace can be
saved to a file by copying and pasting from the terminal (if it's a non-x based
--
gentoo-doc-cvs@gentoo.org mailing list
^ permalink raw reply [flat|nested] 24+ messages in thread* [gentoo-doc-cvs] cvs commit: bugzilla-howto.xml
@ 2005-07-22 23:46 Xavier Neys
0 siblings, 0 replies; 24+ messages in thread
From: Xavier Neys @ 2005-07-22 23:46 UTC (permalink / raw
To: gentoo-doc-cvs
neysx 05/07/22 23:46:11
Modified: xml/htdocs/doc/en bugzilla-howto.xml
Log:
Done some coding style/link fixing
Revision Changes Path
1.5 +131 -146 xml/htdocs/doc/en/bugzilla-howto.xml
file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.5&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.5&content-type=text/plain&cvsroot=gentoo
diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/bugzilla-howto.xml.diff?r1=1.4&r2=1.5&cvsroot=gentoo
Index: bugzilla-howto.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- bugzilla-howto.xml 10 Jul 2005 14:13:08 -0000 1.4
+++ bugzilla-howto.xml 22 Jul 2005 23:46:11 -0000 1.5
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.4 2005/07/10 14:13:08 fox2mike Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.5 2005/07/22 23:46:11 neysx Exp $ -->
<guide link="/doc/en/bugzilla-howto.xml">
<title>Gentoo Bug Reporting Guide</title>
@@ -20,8 +20,8 @@
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>
-<version>1.3</version>
-<date>2005-07-10</date>
+<version>1.4</version>
+<date>2005-07-22</date>
<chapter>
<title>Introduction</title>
@@ -86,11 +86,11 @@
</pre>
<p>
-These errors can be quite troublesome. However, once you find them, what do
-you do? The following sections will look at two important tools for handling
-run time errors. After that, we'll take a look at compile errors, and how to
-handle them. Let's start out with the first tool for debugging run time
-errors -- <c>gdb</c>.
+These errors can be quite troublesome. However, once you find them, what do you
+do? The following sections will look at two important tools for handling run
+time errors. After that, we'll take a look at compile errors, and how to handle
+them. Let's start out with the first tool for debugging run time errors --
+<c>gdb</c>.
</p>
</body>
@@ -111,7 +111,7 @@
program is to <c>emerge</c> the program with <c>FEATURES="nostrip"</c>. This
prevents the stripping of debug symbols. Why are programs stripped by default?
The reason is the same as that for having gzipped man pages -- saving space.
-Here's how the size of a program varies with and without debug symbol stripping.
+Here's how the size of a program varies with and without debug symbol stripping.
</p>
<pre caption="Filesize Comparison">
@@ -128,7 +128,7 @@
the size! Two more things can be done for debugging. The first is adding ggdb3
to your CFLAGS and CXXFLAGS. This flag adds more debugging information than is
generally included. We'll see what that means later on. This is how
-<path>/etc/make.conf</path> <e>might</e> look with the newly added flags.
+<path>/etc/make.conf</path> <e>might</e> look with the newly added flags.
</p>
<pre caption="make.conf settings">
@@ -137,9 +137,9 @@
</pre>
<p>
-Lastly, you can also add debug to the package's USE flags. This can be done with the
-<path>package.use</path> file.
-</p>
+Lastly, you can also add debug to the package's USE flags. This can be done
+with the <path>package.use</path> file.
+</p>
<pre caption="Using package.use to add debug USE flag">
# <i>echo "category/package debug" >> /etc/portage/package.use</i>
@@ -395,7 +395,7 @@
reading in "bar" as it should. In this case, we can recommend the ebuild
maintainer to put a warning about it. For now though, we can copy over the
config file from <path>.foobar</path> and modify it to produce the correct
-results.
+results.
</p>
</body>
@@ -510,9 +510,9 @@
<body>
<p>
-PORT_LOGDIR is a portage variable that sets up a log directory for separate
-emerge logs. Let's take a look and see what that entails. First, run your emerge
-with PORT_LOGDIR set to your favorite log location. Let's say we have a
+PORT_LOGDIR is a portage variable that sets up a log directory for separate
+emerge logs. Let's take a look and see what that entails. First, run your
+emerge with PORT_LOGDIR set to your favorite log location. Let's say we have a
location <path>/var/log/portage</path>. We'll use that for our log directory:
</p>
@@ -639,7 +639,7 @@
<p>
This is how the Advanced Search Page looks like. While it may seem overwhelming
at first, we're going to look at a few simple areas to narrow down the rather
-vague searches bugzilla returns.
+vague searches bugzilla returns.
</p>
<figure link="/images/docs/bugzie-content.png" caption="Content"/>
@@ -759,15 +759,13 @@
<p>
Another common misconception occurs with our Documentation bugs. For example, a
-user finds a bug with the <uri
-link="http://www.gentoo.org/proj/en/releng/catalyst/index.xml">Catalyst
+user finds a bug with the <uri link="/proj/en/releng/catalyst/">Catalyst
Docs</uri>. The general tendency is to file a bug under Docs-user, which gets
assigned to the <uri link="http://gdp.gentoo.org">GDP</uri>, when it should
-actually go to a member of the <uri
-link="http://www.gentoo.org/proj/en/releng/">Release Engineering</uri> team. As
-a rule of thumb, only documentation under http://www.gentoo.org/doc/* is under
-the GDP. Anything under http://www.gentoo.org/proj/* is under the respective
-teams.
+actually go to a member of the <uri link="/proj/en/releng/">Release
+Engineering</uri> team. As a rule of thumb, only documentation under
+<path>http://www.gentoo.org/doc/*</path> is under the GDP. Anything under
+<path>http://www.gentoo.org/proj/*</path> is under the respective teams.
</p>
<note>
@@ -779,8 +777,9 @@
</note>
<p>
-Our bug goes in Gentoo Linux as it's an ebuild bug. We head over there and are presented
-with the multi-step bug reporting process. Let us now proceed with Step 1...
+Our bug goes in Gentoo Linux as it's an ebuild bug. We head over there and are
+presented with the multi-step bug reporting process. Let us now proceed with
+Step 1...
</p>
<figure link="/images/docs/bugzie-guide-step1.png" caption="Guided Format Step 1"/>
@@ -808,22 +807,23 @@
<ul>
<li>
- First, there's the Product. The product will narrow down the bug to a
- specific area of Gentoo like Bugzilla (for bugs relating to bugs.gentoo.org),
- Docs-user(for User Documentation) or Gentoo Linux (for ebuilds and the like).
+ First, there's the Product. The product will narrow down the bug to a
+ specific area of Gentoo like Bugzilla (for bugs relating to
+ bugs.gentoo.org), Docs-user(for User Documentation) or Gentoo Linux (for
+ ebuilds and the like).
</li>
<li>
- Component is where exactly the problem occurs, more specifically which part
- of selected product the bug comes under. This makes classification easier.
+ Component is where exactly the problem occurs, more specifically which part
+ of selected product the bug comes under. This makes classification easier.
</li>
<li>
- Hardware platform is what architecture you're running. If you were running
- SPARC, you would set it to SPARC.
+ Hardware platform is what architecture you're running. If you were running
+ SPARC, you would set it to SPARC.
</li>
<li>
- Operating System is what Operating System you're using. Because Gentoo is
- considered a "Meta-distribution", it can run on other operating systems
- beside Linux.
+ Operating System is what Operating System you're using. Because Gentoo is
+ considered a "Meta-distribution", it can run on other operating systems
+ beside Linux.
</li>
</ul>
@@ -832,34 +832,27 @@
</p>
<ul>
- <li>
- Product - Gentoo Linux (Since it is an ebuild issue)
- </li>
- <li>
- Component - Application (It is an application at fault, foobar2)
- </li>
- <li>
- Hardware Platform - All (This error could occur across architectures)
- </li>
- <li>
- Operation System - All (It could occur on all types of systems)
- </li>
+ <li>Product - Gentoo Linux (Since it is an ebuild issue)</li>
+ <li>Component - Application (It is an application at fault, foobar2)</li>
+ <li>Hardware Platform - All (This error could occur across architectures)</li>
+ <li>Operation System - All (It could occur on all types of systems)</li>
</ul>
<figure link="/images/docs/bugzie-basic-comp.png" caption="Completed Basic Information"/>
<ul>
<li>
--
gentoo-doc-cvs@gentoo.org mailing list
^ permalink raw reply [flat|nested] 24+ messages in thread
* [gentoo-doc-cvs] cvs commit: bugzilla-howto.xml
@ 2005-07-13 5:48 Shyam Mani
0 siblings, 0 replies; 24+ messages in thread
From: Shyam Mani @ 2005-07-13 5:48 UTC (permalink / raw
To: gentoo-doc-cvs
fox2mike 05/07/13 05:48:11
Added: xml/htdocs/doc/en/draft bugzilla-howto.xml
Log:
Initial version of the split bugzilla guide, for comments + suggestions + additions.
Revision Changes Path
1.9 +446 -647 xml/htdocs/doc/en/draft/bugzilla-howto.xml
file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/bugzilla-howto.xml?rev=1.9&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/bugzilla-howto.xml?rev=1.9&content-type=text/plain&cvsroot=gentoo
diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/bugzilla-howto.xml.diff?r1=1.8&r2=1.9&cvsroot=gentoo
--
gentoo-doc-cvs@gentoo.org mailing list
^ permalink raw reply [flat|nested] 24+ messages in thread
* [gentoo-doc-cvs] cvs commit: bugzilla-howto.xml
@ 2005-07-10 14:13 Shyam Mani
0 siblings, 0 replies; 24+ messages in thread
From: Shyam Mani @ 2005-07-10 14:13 UTC (permalink / raw
To: gentoo-doc-cvs
fox2mike 05/07/10 14:13:08
Modified: xml/htdocs/doc/en bugzilla-howto.xml
Log:
Fixed gddb -> ggdb, which is correct.
Revision Changes Path
1.4 +4 -4 xml/htdocs/doc/en/bugzilla-howto.xml
file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.4&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.4&content-type=text/plain&cvsroot=gentoo
diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/bugzilla-howto.xml.diff?r1=1.3&r2=1.4&cvsroot=gentoo
Index: bugzilla-howto.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- bugzilla-howto.xml 9 Jul 2005 22:31:57 -0000 1.3
+++ bugzilla-howto.xml 10 Jul 2005 14:13:08 -0000 1.4
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.3 2005/07/09 22:31:57 fox2mike Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.4 2005/07/10 14:13:08 fox2mike Exp $ -->
<guide link="/doc/en/bugzilla-howto.xml">
<title>Gentoo Bug Reporting Guide</title>
@@ -20,7 +20,7 @@
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>
-<version>1.2</version>
+<version>1.3</version>
<date>2005-07-10</date>
<chapter>
@@ -132,7 +132,7 @@
</p>
<pre caption="make.conf settings">
-CFLAGS="-O2 -pipe -gddb3"
+CFLAGS="-O2 -pipe -ggdb3"
CXXFLAGS="${CFLAGS}"
</pre>
@@ -312,7 +312,7 @@
<p>
As you can see, -ggdb3 adds about <e>13178</e> more bytes to the file size over the one
with debugging symbols. However, as shown above, this increase in file size can
-be worth it if presenting debug information to developers. The backtrace, can be
+be worth it if presenting debug information to developers. The backtrace can be
saved to a file by copying and pasting from the terminal (if it's a non-x based
terminal, you can use gpm. To keep this doc simple, I recommend you read up on
the documentation for gpm to see how to copy and paste with it). Now that we're
--
gentoo-doc-cvs@gentoo.org mailing list
^ permalink raw reply [flat|nested] 24+ messages in thread* [gentoo-doc-cvs] cvs commit: bugzilla-howto.xml
@ 2005-07-09 22:31 Shyam Mani
0 siblings, 0 replies; 24+ messages in thread
From: Shyam Mani @ 2005-07-09 22:31 UTC (permalink / raw
To: gentoo-doc-cvs
fox2mike 05/07/09 22:31:57
Modified: xml/htdocs/doc/en bugzilla-howto.xml
Log:
Major updates to the guide. GuideXML corrections, content and grammer changes along with a few section additions. IMPORTANT : Translators, Please do not commence work on this guide for the next couple of days as the guide may see drastic changes. See gentoo-doc ML for details. Thanks.
Revision Changes Path
1.3 +539 -210 xml/htdocs/doc/en/bugzilla-howto.xml
file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.3&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.3&content-type=text/plain&cvsroot=gentoo
diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/bugzilla-howto.xml.diff?r1=1.2&r2=1.3&cvsroot=gentoo
Index: bugzilla-howto.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- bugzilla-howto.xml 7 Jul 2005 18:19:23 -0000 1.2
+++ bugzilla-howto.xml 9 Jul 2005 22:31:57 -0000 1.3
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.2 2005/07/07 18:19:23 fox2mike Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.3 2005/07/09 22:31:57 fox2mike Exp $ -->
<guide link="/doc/en/bugzilla-howto.xml">
<title>Gentoo Bug Reporting Guide</title>
@@ -20,8 +20,8 @@
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>
-<version>1.1</version>
-<date>2005-07-07</date>
+<version>1.2</version>
+<date>2005-07-10</date>
<chapter>
<title>Introduction</title>
@@ -30,24 +30,24 @@
<body>
<p>
-Often one of the factors that delay a bug being fixed is how it is reported. By
-creating this guide, I hope to help improve the communication between
+One of the factors that delay a bug being fixed is the way it is reported. By
+creating this guide, we hope to help improve the communication between
developers and users in bug resolution. Getting bugs fixed is an important, if
-not crucial part of the quality assurance of any project and hopefully this
+not crucial part of the quality assurance for any project and hopefully this
guide will help make that a success.
</p>
</body>
</section>
<section>
-<title>Initial Finding</title>
+<title>Bugs!!!!</title>
<body>
<p>
-You're emerge-ing a package or working with a program, then suddenly the worst
-happens -- you find a bug. Bugs come in many forms, whether it be emerge
-failures or segmentation faults. Whatever the cause, the fact still remains that
-such a bug must be fixed. Here is a few examples of such bugs.
+You're emerge-ing a package or working with a program and suddenly the worst
+happens -- you find a bug. Bugs come in many forms like emerge failures or
+segmentation faults. Whatever the cause, the fact still remains that such a bug
+must be fixed. Here is a few examples of such bugs.
</p>
<pre caption="A run time error">
@@ -87,10 +87,10 @@
<p>
These errors can be quite troublesome. However, once you find them, what do
-you do? The following sections will look at 2 important tools for handling
+you do? The following sections will look at two important tools for handling
run time errors. After that, we'll take a look at compile errors, and how to
handle them. Let's start out with the first tool for debugging run time
-errors -- <c>gdb</c>
+errors -- <c>gdb</c>.
</p>
</body>
@@ -108,10 +108,10 @@
GDB, or the (G)NU (D)e(B)ugger, is a program used to find run time errors that
normally involve memory corruption. First off, let's take a look at what
debugging entails. One of the main things you must do in order to debug a
-program is to <c>emerge</c> the program with FEATURES="nostrip". This prevents
-the stripping of debug symbols. Why are programs stripped by default? The reason
-is the same as that for having gzipped man pages -- saving space. Here's how the
-size of a program varies with and without debug symbol stripping.
+program is to <c>emerge</c> the program with <c>FEATURES="nostrip"</c>. This
+prevents the stripping of debug symbols. Why are programs stripped by default?
+The reason is the same as that for having gzipped man pages -- saving space.
+Here's how the size of a program varies with and without debug symbol stripping.
</p>
<pre caption="Filesize Comparison">
@@ -125,10 +125,19 @@
Just for reference, <e>bad_code</e> is the program we'll be debugging with
<c>gdb</c> later on. As you can see, the program without debugging symbols is
3140 bytes, while the program with them is 6374 bytes. That's close to double
-the size! Two more things can be done for debugging. The first is adding -g to
-your CFLAGS and CXXFLAGS. This flag adds more debugging information than is
-generally included. We'll see what that means later on. Lastly, you can also add
-debug to the package's USE flags. This can be done with the
+the size! Two more things can be done for debugging. The first is adding ggdb3
+to your CFLAGS and CXXFLAGS. This flag adds more debugging information than is
+generally included. We'll see what that means later on. This is how
+<path>/etc/make.conf</path> <e>might</e> look with the newly added flags.
+</p>
+
+<pre caption="make.conf settings">
+CFLAGS="-O2 -pipe -gddb3"
+CXXFLAGS="${CFLAGS}"
+</pre>
+
+<p>
+Lastly, you can also add debug to the package's USE flags. This can be done with the
<path>package.use</path> file.
</p>
@@ -144,8 +153,8 @@
</note>
<p>
-Now that that's done, you will need to re-emerge your package to set the
-new debug settings into place. This can be done as follows:
+Then we re-emerge the package with the modifications we've done so far as shown
+below.
</p>
<pre caption="Re-emergeing a package with debugging">
@@ -163,9 +172,8 @@
<body>
<p>
-Let's say we have a program here called "bad_code" (I know, it's sort of cheesy
-but..). Some person claims he can break the code and provides an example. You go
-ahead and test it out:
+Let's say we have a program here called "bad_code". Some person claims that the
+program crashes and provides an example. You go ahead and test it out:
</p>
<pre caption="Breaking The Program">
@@ -191,14 +199,20 @@
This GDB was configured as "i686-pc-linux-gnu"...Using host libthread_db library "/lib/libthread_db.so.1".
</pre>
+<note>
+One can also debug with core dumps. These core files contain the same
+information that the program would produce when run with gdb. In order to debug
+with a core file with bad_code, you would run <c>gdb ./bad_code core</c> where
+core is the name of the core file.
+</note>
+
<p>
-You should see a small terminal like setup after that which says "(gdb)" and
-waits for input. First, we have to run the program. We type in <c>run</c> at the
-command and receive a notice like:
+You should see a prompt that says "(gdb)" and waits for input. First, we have to
+run the program. We type in <c>run</c> at the command and receive a notice like:
</p>
<pre caption="Running the program in GDB">
-(gdb) run
+(gdb) <i>run</i>
Starting program: /home/chris/bad_code
Program received signal SIGSEGV, Segmentation fault.
@@ -219,22 +233,23 @@
</p>
<pre caption="Program backtrace">
-(gdb) bt
+(gdb) <i>bt</i>
#0 0xb7ec6dc0 in strcpy () from /lib/libc.so.6
#1 0x0804838c in run_it ()
#2 0x080483ba in main ()
</pre>
<p>
-So as we see here, first main() was run, then run_it(), and somewhere in run_it
-lies the strcpy() at fault. Things such as this help developers narrow things
-down. Now, there are a few exceptions to the output. First off is forgetting
-to disable debug symbols with FEATURES="nostrip". With debug symbols stripped,
-output looks something like this:
+You can notice the trace pattern clearly. main() is called first, followed by
+run_it(), and somewhere in run_it() lies the strcpy() at fault. Things such as
+this help developers narrow down problems. There are a few exceptions to the
+output. First off is forgetting to enable debug symbols with
+<c>FEATURES="nostrip"</c>. With debug symbols stripped, the output looks something
+like this:
</p>
<pre caption="Program backtrace With debug symbols stripped">
-(gdb) bt
+(gdb) <i>bt</i>
#0 0xb7e2cdc0 in strcpy () from /lib/libc.so.6
#1 0x0804838c in ?? ()
#2 0xbfd19510 in ?? ()
@@ -264,13 +279,14 @@
<p>
This backtrace contains a large number of ?? marks. This is because without
-debug symbols, <c>gdb</c> doesn't know how the program was ran. Hence, it is
-crucial that debug symbols are <e>not</e> stripped. Now remember a while ago I
-told you about the -g flag. Let's see what the output looks like with that:
+debug symbols, <c>gdb</c> doesn't know how the program was run. Hence, it is
--
gentoo-doc-cvs@gentoo.org mailing list
^ permalink raw reply [flat|nested] 24+ messages in thread* [gentoo-doc-cvs] cvs commit: bugzilla-howto.xml
@ 2005-07-07 18:19 Shyam Mani
0 siblings, 0 replies; 24+ messages in thread
From: Shyam Mani @ 2005-07-07 18:19 UTC (permalink / raw
To: gentoo-doc-cvs
fox2mike 05/07/07 18:19:23
Modified: xml/htdocs/doc/en bugzilla-howto.xml
Log:
Fixed http -> https in a Bugzie link. Added a few <path> tags where needed.
Revision Changes Path
1.2 +23 -22 xml/htdocs/doc/en/bugzilla-howto.xml
file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.2&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.2&content-type=text/plain&cvsroot=gentoo
diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/bugzilla-howto.xml.diff?r1=1.1&r2=1.2&cvsroot=gentoo
Index: bugzilla-howto.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- bugzilla-howto.xml 7 Jul 2005 12:02:21 -0000 1.1
+++ bugzilla-howto.xml 7 Jul 2005 18:19:23 -0000 1.2
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.1 2005/07/07 12:02:21 fox2mike Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.2 2005/07/07 18:19:23 fox2mike Exp $ -->
<guide link="/doc/en/bugzilla-howto.xml">
<title>Gentoo Bug Reporting Guide</title>
@@ -20,7 +20,7 @@
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>
-<version>1.0</version>
+<version>1.1</version>
<date>2005-07-07</date>
<chapter>
@@ -364,8 +364,8 @@
</pre>
<p>
-This creates a file called strace.log in the current directory. We check the
-file, and shown below are the relevant parts from the file.
+This creates a file called <path>strace.log</path> in the current directory. We
+check the file, and shown below are the relevant parts from the file.
</p>
<pre caption="A Look At the strace Log">
@@ -378,7 +378,8 @@
<path>.foobar2</path> instead of <path>.foobar</path>. We also see the program
reading in "bar" as it should. In this case, we can recommend the ebuild
maintainer to put a warning about it. For now though, we can copy over the
-config file from .foobar and modify it to produce the correct results.
+config file from <path>.foobar</path> and modify it to produce the correct
+results.
</p>
</body>
@@ -584,7 +585,7 @@
<p>
So to begin searching, we head over to the <uri
-link="http://bugs.gentoo.org/">Bugzilla Homepage</uri>.
+link="https://bugs.gentoo.org/">Bugzilla Homepage</uri>.
</p>
<figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/>
@@ -964,24 +965,24 @@
<ul>
<li>
- UNCONFIRMED - You're generally not going to see this too often. This
+ UNCONFIRMED - You're generally not going to see this too often. This
means that a bug reporter has opened a bug using the advanced method and is
uncertain his or her bug is an actual bug.
- </li>
+ </li>
<li>
- NEW - Bugs that are first opened are considered new.
- </li>
+ NEW - Bugs that are first opened are considered new.
+ </li>
<li>
- ASSIGNED - When the person you've assigned the bug too validates your
+ ASSIGNED - When the person you've assigned the bug too validates your
bug, it will often receive ASSIGNED status while they figure out the issue.
This let's you know that they've accepted your bug as a real bug.
- </li>
+ </li>
<li>
- REOPENED - Someone has resolved a bug and you think the solution is not
+ REOPENED - Someone has resolved a bug and you think the solution is not
feasible or the problem still persists. At this point, you may re-open the
bug. However <b>please do not abuse this</b>. If a developer closes the bug a
second or even third time, chances are that your bug is closed.
- </li>
+ </li>
</ul>
<p>
@@ -1007,21 +1008,21 @@
<ul>
<li>
- FIXED - The bug is fixed, follow the instructions to resolve your
+ FIXED - The bug is fixed, follow the instructions to resolve your
issue.
- </li>
+ </li>
<li>
- INVALID - You did not do something specifically documented, causing the
+ INVALID - You did not do something specifically documented, causing the
bug
- </li>
+ </li>
<li>
- DUPLICATE - You didn't use this guide and reported a duplicate bug
+ DUPLICATE - You didn't use this guide and reported a duplicate bug
:)
- </li>
+ </li>
<li>
- WORKSFORME - Developer/person assigned the bug cannot reproduce your
+ WORKSFORME - Developer/person assigned the bug cannot reproduce your
error
- </li>
+ </li>
</ul>
</body>
--
gentoo-doc-cvs@gentoo.org mailing list
^ permalink raw reply [flat|nested] 24+ messages in thread
* [gentoo-doc-cvs] cvs commit: bugzilla-howto.xml
@ 2005-07-07 12:03 Shyam Mani
0 siblings, 0 replies; 24+ messages in thread
From: Shyam Mani @ 2005-07-07 12:03 UTC (permalink / raw
To: gentoo-doc-cvs
fox2mike 05/07/07 12:03:35
Removed: xml/htdocs/doc/en/draft bugzilla-howto.xml
Log:
Doc went live, removing from draft.
--
gentoo-doc-cvs@gentoo.org mailing list
^ permalink raw reply [flat|nested] 24+ messages in thread
* [gentoo-doc-cvs] cvs commit: bugzilla-howto.xml
@ 2005-07-07 12:02 Shyam Mani
0 siblings, 0 replies; 24+ messages in thread
From: Shyam Mani @ 2005-07-07 12:02 UTC (permalink / raw
To: gentoo-doc-cvs
fox2mike 05/07/07 12:02:21
Added: xml/htdocs/doc/en bugzilla-howto.xml
Log:
#97274 - Initial version of the doc, Lots of thanks to Chris "Da PUNK" White :)
Revision Changes Path
1.1 xml/htdocs/doc/en/bugzilla-howto.xml
file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo
Index: bugzilla-howto.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.1 2005/07/07 12:02:21 fox2mike Exp $ -->
<guide link="/doc/en/bugzilla-howto.xml">
<title>Gentoo Bug Reporting Guide</title>
<author title="Author">
<mail link="chriswhite@gentoo.org">Chris White</mail>
</author>
<author title="Editor">
<mail link="fox2mike@gentoo.org">Shyam Mani</mail>
</author>
<abstract>
This document shows the proper method of reporting bugs using Bugzilla.
</abstract>
<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>
<version>1.0</version>
<date>2005-07-07</date>
<chapter>
<title>Introduction</title>
<section>
<title>Preface</title>
<body>
<p>
Often one of the factors that delay a bug being fixed is how it is reported. By
creating this guide, I hope to help improve the communication between
developers and users in bug resolution. Getting bugs fixed is an important, if
not crucial part of the quality assurance of any project and hopefully this
guide will help make that a success.
</p>
</body>
</section>
<section>
<title>Initial Finding</title>
<body>
<p>
You're emerge-ing a package or working with a program, then suddenly the worst
happens -- you find a bug. Bugs come in many forms, whether it be emerge
failures or segmentation faults. Whatever the cause, the fact still remains that
such a bug must be fixed. Here is a few examples of such bugs.
</p>
<pre caption="A run time error">
$ <i>./bad_code `perl -e 'print Ax100'`</i>
Segmentation fault
</pre>
<pre caption="An emerge failure">
/usr/lib/gcc-lib/i686-pc-linux-gnu/3.3.2/include/g++-v3/backward/backward_warning.h:32:2:
warning: #warning This file includes at least one deprecated or antiquated
header. Please consider using one of the 32 headers found in section 17.4.1.2 of
the C++ standard. Examples include substituting the <X> header for the <X.h>
header for C++ includes, or <sstream> instead of the deprecated header
<strstream.h>. To disable this warning use -Wno-deprecated.
In file included from main.cc:40:
menudef.h:55: error: brace-enclosed initializer used to initialize `
OXPopupMenu*'
menudef.h:62: error: brace-enclosed initializer used to initialize `
OXPopupMenu*'
menudef.h:70: error: brace-enclosed initializer used to initialize `
OXPopupMenu*'
menudef.h:78: error: brace-enclosed initializer used to initialize `
OXPopupMenu*'
main.cc: In member function `void OXMain::DoOpen()':
main.cc:323: warning: unused variable `FILE*fp'
main.cc: In member function `void OXMain::DoSave(char*)':
main.cc:337: warning: unused variable `FILE*fp'
make[1]: *** [main.o] Error 1
make[1]: Leaving directory
`/var/tmp/portage/xclass-0.7.4/work/xclass-0.7.4/example-app'
make: *** [shared] Error 2
!!! ERROR: x11-libs/xclass-0.7.4 failed.
!!! Function src_compile, Line 29, Exitcode 2
!!! 'emake shared' failed
</pre>
<p>
These errors can be quite troublesome. However, once you find them, what do
you do? The following sections will look at 2 important tools for handling
run time errors. After that, we'll take a look at compile errors, and how to
handle them. Let's start out with the first tool for debugging run time
errors -- <c>gdb</c>
</p>
</body>
</section>
</chapter>
<chapter>
<title>Debugging using GDB</title>
<section>
<title>Introduction</title>
<body>
<p>
GDB, or the (G)NU (D)e(B)ugger, is a program used to find run time errors that
normally involve memory corruption. First off, let's take a look at what
debugging entails. One of the main things you must do in order to debug a
program is to <c>emerge</c> the program with FEATURES="nostrip". This prevents
the stripping of debug symbols. Why are programs stripped by default? The reason
is the same as that for having gzipped man pages -- saving space. Here's how the
size of a program varies with and without debug symbol stripping.
</p>
<pre caption="Filesize Comparison">
<comment>(debug symbols stripped)</comment>
-rwxr-xr-x 1 chris users 3140 6/28 13:11 bad_code
<comment>(debug symbols intact)</comment>
-rwxr-xr-x 1 chris users 6374 6/28 13:10 bad_code
</pre>
<p>
Just for reference, <e>bad_code</e> is the program we'll be debugging with
<c>gdb</c> later on. As you can see, the program without debugging symbols is
3140 bytes, while the program with them is 6374 bytes. That's close to double
the size! Two more things can be done for debugging. The first is adding -g to
your CFLAGS and CXXFLAGS. This flag adds more debugging information than is
generally included. We'll see what that means later on. Lastly, you can also add
debug to the package's USE flags. This can be done with the
<path>package.use</path> file.
</p>
<pre caption="Using package.use to add debug USE flag">
# <i>echo "category/package debug" >> /etc/portage/package.use</i>
</pre>
<note>
The directory <path>/etc/portage</path> does not exist by default and you may
have to create it, if you have not already done so. If the package already has
USE flags set in <path>package.use</path>, you will need to manually modify them
in your favorite editor.
</note>
<p>
Now that that's done, you will need to re-emerge your package to set the
new debug settings into place. This can be done as follows:
</p>
<pre caption="Re-emergeing a package with debugging">
# <i>FEATURES="nostrip" emerge package</i>
</pre>
<p>
Now that debug symbols are setup, we can continue with debugging the program.
</p>
</body>
</section>
<section>
<title>Running the program with GDB</title>
<body>
<p>
Let's say we have a program here called "bad_code" (I know, it's sort of cheesy
but..). Some person claims he can break the code and provides an example. You go
ahead and test it out:
</p>
<pre caption="Breaking The Program">
$ <i>./bad_code `perl -e 'print Ax100'`</i>
Segmentation fault
</pre>
<p>
It seems this person was right. Since the program is obviously broken, we have
a bug at hand. Now, it's time to use <c>gdb</c> to help solve this matter. First
we run <c>gdb</c> with <c>--args</c>, then give it the full program with
arguments like shown:
</p>
<pre caption="Running Our Program Through GDB">
$ <i>gdb --args ./bad_code `perl -e 'print Ax100'`</i>
GNU gdb 6.3
Copyright 2004 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB. Type "show warranty" for details.
This GDB was configured as "i686-pc-linux-gnu"...Using host libthread_db library "/lib/libthread_db.so.1".
</pre>
<p>
You should see a small terminal like setup after that which says "(gdb)" and
waits for input. First, we have to run the program. We type in <c>run</c> at the
command and receive a notice like:
</p>
--
gentoo-doc-cvs@gentoo.org mailing list
^ permalink raw reply [flat|nested] 24+ messages in thread
* [gentoo-doc-cvs] cvs commit: bugzilla-howto.xml
@ 2005-07-07 11:56 Sven Vermeulen
0 siblings, 0 replies; 24+ messages in thread
From: Sven Vermeulen @ 2005-07-07 11:56 UTC (permalink / raw
To: gentoo-doc-cvs
swift 05/07/07 11:56:02
Modified: xml/htdocs/doc/en/draft bugzilla-howto.xml
Log:
Add #emerge_error for quick reference
Revision Changes Path
1.7 +2 -2 xml/htdocs/doc/en/draft/bugzilla-howto.xml
file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/bugzilla-howto.xml?rev=1.7&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/bugzilla-howto.xml?rev=1.7&content-type=text/plain&cvsroot=gentoo
diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/bugzilla-howto.xml.diff?r1=1.6&r2=1.7&cvsroot=gentoo
Index: bugzilla-howto.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/bugzilla-howto.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- bugzilla-howto.xml 7 Jul 2005 11:55:05 -0000 1.6
+++ bugzilla-howto.xml 7 Jul 2005 11:56:02 -0000 1.7
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/bugzilla-howto.xml,v 1.6 2005/07/07 11:55:05 fox2mike Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/bugzilla-howto.xml,v 1.7 2005/07/07 11:56:02 swift Exp $ -->
<guide link="/doc/en/bugzilla-howto.xml">
<title>Gentoo Bug Reporting Guide</title>
@@ -413,7 +413,7 @@
</body>
</section>
-<section>
+<section id="emerge_error">
<title>Evaluating emerge Errors</title>
<body>
--
gentoo-doc-cvs@gentoo.org mailing list
^ permalink raw reply [flat|nested] 24+ messages in thread
* [gentoo-doc-cvs] cvs commit: bugzilla-howto.xml
@ 2005-07-07 11:55 Shyam Mani
0 siblings, 0 replies; 24+ messages in thread
From: Shyam Mani @ 2005-07-07 11:55 UTC (permalink / raw
To: gentoo-doc-cvs
fox2mike 05/07/07 11:55:05
Modified: xml/htdocs/doc/en/draft bugzilla-howto.xml
Log:
Removed unwanted <note>.
Revision Changes Path
1.6 +5 -9 xml/htdocs/doc/en/draft/bugzilla-howto.xml
file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/bugzilla-howto.xml?rev=1.6&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/bugzilla-howto.xml?rev=1.6&content-type=text/plain&cvsroot=gentoo
diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/bugzilla-howto.xml.diff?r1=1.5&r2=1.6&cvsroot=gentoo
Index: bugzilla-howto.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/bugzilla-howto.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- bugzilla-howto.xml 7 Jul 2005 11:47:29 -0000 1.5
+++ bugzilla-howto.xml 7 Jul 2005 11:55:05 -0000 1.6
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/bugzilla-howto.xml,v 1.5 2005/07/07 11:47:29 swift Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/bugzilla-howto.xml,v 1.6 2005/07/07 11:55:05 fox2mike Exp $ -->
<guide link="/doc/en/bugzilla-howto.xml">
<title>Gentoo Bug Reporting Guide</title>
@@ -537,9 +537,10 @@
<p>
<uri link="http://www.bugzilla.org">Bugzilla</uri> is what we at Gentoo use to
handle bugs. Gentoo's Bugzilla is reachable by HTTPS and HTTP. HTTPS is
-available for those on insecure networks. For the sake of consistency, I will be
-using the HTTPS version in the examples to follow. Head over to <uri
-link="https://bugs.gentoo.org">Gentoo Bugs</uri> to see how it looks.
+available for those on insecure networks or simply paranoid :). For the sake of
+consistency, I will be using the HTTPS version in the examples to follow. Head
+over to <uri link="https://bugs.gentoo.org">Gentoo Bugs</uri> to see how it
+looks.
</p>
<p>
@@ -586,11 +587,6 @@
link="http://bugs.gentoo.org/">Bugzilla Homepage</uri>.
</p>
-<note>
-Bugzilla is reachable at <uri>http://bugs.gentoo.org</uri> and
-<uri>https://bugs.gentoo.org</uri> for the paranoid :)
-</note>
-
<figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/>
<p>
--
gentoo-doc-cvs@gentoo.org mailing list
^ permalink raw reply [flat|nested] 24+ messages in thread
* [gentoo-doc-cvs] cvs commit: bugzilla-howto.xml
@ 2005-07-07 11:47 Sven Vermeulen
0 siblings, 0 replies; 24+ messages in thread
From: Sven Vermeulen @ 2005-07-07 11:47 UTC (permalink / raw
To: gentoo-doc-cvs
swift 05/07/07 11:47:29
Modified: xml/htdocs/doc/en/draft bugzilla-howto.xml
Log:
Further spelling and grammar and language stuff
Revision Changes Path
1.5 +10 -10 xml/htdocs/doc/en/draft/bugzilla-howto.xml
file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/bugzilla-howto.xml?rev=1.5&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/bugzilla-howto.xml?rev=1.5&content-type=text/plain&cvsroot=gentoo
diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/bugzilla-howto.xml.diff?r1=1.4&r2=1.5&cvsroot=gentoo
Index: bugzilla-howto.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/bugzilla-howto.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- bugzilla-howto.xml 7 Jul 2005 11:38:19 -0000 1.4
+++ bugzilla-howto.xml 7 Jul 2005 11:47:29 -0000 1.5
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/bugzilla-howto.xml,v 1.4 2005/07/07 11:38:19 swift Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/bugzilla-howto.xml,v 1.5 2005/07/07 11:47:29 swift Exp $ -->
<guide link="/doc/en/bugzilla-howto.xml">
<title>Gentoo Bug Reporting Guide</title>
@@ -265,7 +265,7 @@
<p>
This backtrace contains a large number of ?? marks. This is because without
debug symbols, <c>gdb</c> doesn't know how the program was ran. Hence, it is
-crucial that debug symbols are <e>not</e> stripped. Now remember awhile ago I
+crucial that debug symbols are <e>not</e> stripped. Now remember a while ago I
told you about the -g flag. Let's see what the output looks like with that:
</p>
@@ -485,8 +485,8 @@
<body>
<p>
-PORT_LOGDIR is a portage variable that sets up a log directory for individual emerge
-logs. Let's take a look and see what that entails. First, run your emerge
+PORT_LOGDIR is a portage variable that sets up a log directory for separate
+emerge logs. Let's take a look and see what that entails. First, run your emerge
with PORT_LOGDIR set to your favorite log location. Let's say we have a
location /var/log/portage. We'll use that for our log directory:
</p>
@@ -536,7 +536,7 @@
<p>
<uri link="http://www.bugzilla.org">Bugzilla</uri> is what we at Gentoo use to
-handle bugs. Gentoo's Bugzilla is reachable by both HTTPS and HTTP. HTTPS is
+handle bugs. Gentoo's Bugzilla is reachable by HTTPS and HTTP. HTTPS is
available for those on insecure networks. For the sake of consistency, I will be
using the HTTPS version in the examples to follow. Head over to <uri
link="https://bugs.gentoo.org">Gentoo Bugs</uri> to see how it looks.
@@ -777,11 +777,11 @@
If you were running SPARC, you would set it to SPARC. For this example, we know
this error can occur on multiple architectures, so we'll select All. Operating
System is what Operating System you're using. Because Gentoo is considered a
-"Meta-distribution", it can run on other OSs besides Linux. Examples are
-Gentoo on MacOS, Gentoo on FreeBSD, etc. For this example, we'll select All, as
-this can occur on all types of systems. Build Identifier is what is being used
-to report the bugs (for logging purposes).You can just leave this as is. Let's
-see what we have so far:
+"Meta-distribution", it can run on other operating systems beside Linux.
+Examples are Gentoo on MacOS, Gentoo on FreeBSD, etc. For this example,
+we'll select All, as this can occur on all types of systems. Build Identifier
+is what is being used to report the bugs (for logging purposes). You can just
+leave this as is. Let's see what we have so far:
</p>
<figure link="/images/docs/bugzie-basic-comp.png" caption="Completed Basic Information"/>
--
gentoo-doc-cvs@gentoo.org mailing list
^ permalink raw reply [flat|nested] 24+ messages in thread
* [gentoo-doc-cvs] cvs commit: bugzilla-howto.xml
@ 2005-07-07 11:38 Sven Vermeulen
0 siblings, 0 replies; 24+ messages in thread
From: Sven Vermeulen @ 2005-07-07 11:38 UTC (permalink / raw
To: gentoo-doc-cvs
swift 05/07/07 11:38:19
Modified: xml/htdocs/doc/en/draft bugzilla-howto.xml
Log:
Fix use of access
Revision Changes Path
1.4 +12 -11 xml/htdocs/doc/en/draft/bugzilla-howto.xml
file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/bugzilla-howto.xml?rev=1.4&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/bugzilla-howto.xml?rev=1.4&content-type=text/plain&cvsroot=gentoo
diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/bugzilla-howto.xml.diff?r1=1.3&r2=1.4&cvsroot=gentoo
Index: bugzilla-howto.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/bugzilla-howto.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- bugzilla-howto.xml 7 Jul 2005 11:35:16 -0000 1.3
+++ bugzilla-howto.xml 7 Jul 2005 11:38:19 -0000 1.4
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/bugzilla-howto.xml,v 1.3 2005/07/07 11:35:16 swift Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/bugzilla-howto.xml,v 1.4 2005/07/07 11:38:19 swift Exp $ -->
<guide link="/doc/en/bugzilla-howto.xml">
<title>Gentoo Bug Reporting Guide</title>
@@ -327,14 +327,15 @@
<body>
<p>
-Programs often use files to get configuration information, access hardware, or
-write logs. Often a program attempts to access such files incorrectly. A
-program called <c>strace</c> was created to help deal with this. <c>strace</c>
-traces system calls (hence the name) which mainly include accessing memory and
-files. For our example, we're going to take a program foobar2. This is an
-updated version of foobar. However, during the changeover to foobar2, you notice
-all your configurations are missing! In foobar version 1, you had it setup to
-say "foo", but now it's using the default "bar".
+Programs often use files to get configuration information, get access
+to hardware, or write logs. Often a program attempts to reach such files
+incorrectly. A program called <c>strace</c> was created to help deal with
+this. <c>strace</c> traces system calls (hence the name) which include
+calls that use the memory and files. For our example, we're going to take a
+program foobar2. This is an updated version of foobar. However, during the
+changeover to foobar2, you notice all your configurations are missing! In
+foobar version 1, you had it setup to say "foo", but now it's using the default
+"bar".
</p>
<pre caption="Foobar2 With an invalid configuration">
@@ -535,7 +536,7 @@
<p>
<uri link="http://www.bugzilla.org">Bugzilla</uri> is what we at Gentoo use to
-handle bugs. Gentoo's Bugzilla is accessible by both HTTPS and HTTP. HTTPS is
+handle bugs. Gentoo's Bugzilla is reachable by both HTTPS and HTTP. HTTPS is
available for those on insecure networks. For the sake of consistency, I will be
using the HTTPS version in the examples to follow. Head over to <uri
link="https://bugs.gentoo.org">Gentoo Bugs</uri> to see how it looks.
@@ -917,7 +918,7 @@
Then hit the Commit button for the changes to take place. The bug has been
reassigned to me. Shortly afterward, you notice (by email usually) that I've
responded to your bug. I've stated that I'd like to see an strace log to figure
-out how the program is trying to access your configuration file. You follow the
+out how the program is trying to reach your configuration file. You follow the
previous instructions on using strace and obtain an strace log. Now you need to
attach it to the bug. In order to do this, click on "Create A New Attachment".
</p>
--
gentoo-doc-cvs@gentoo.org mailing list
^ permalink raw reply [flat|nested] 24+ messages in thread
* [gentoo-doc-cvs] cvs commit: bugzilla-howto.xml
@ 2005-07-07 11:35 Sven Vermeulen
0 siblings, 0 replies; 24+ messages in thread
From: Sven Vermeulen @ 2005-07-07 11:35 UTC (permalink / raw
To: gentoo-doc-cvs
swift 05/07/07 11:35:16
Modified: xml/htdocs/doc/en/draft bugzilla-howto.xml
Log:
Spelling fixes, first run
Revision Changes Path
1.3 +13 -13 xml/htdocs/doc/en/draft/bugzilla-howto.xml
file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/bugzilla-howto.xml?rev=1.3&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/bugzilla-howto.xml?rev=1.3&content-type=text/plain&cvsroot=gentoo
diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/bugzilla-howto.xml.diff?r1=1.2&r2=1.3&cvsroot=gentoo
Index: bugzilla-howto.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/bugzilla-howto.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- bugzilla-howto.xml 7 Jul 2005 11:24:54 -0000 1.2
+++ bugzilla-howto.xml 7 Jul 2005 11:35:16 -0000 1.3
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/bugzilla-howto.xml,v 1.2 2005/07/07 11:24:54 fox2mike Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/bugzilla-howto.xml,v 1.3 2005/07/07 11:35:16 swift Exp $ -->
<guide link="/doc/en/bugzilla-howto.xml">
<title>Gentoo Bug Reporting Guide</title>
@@ -280,7 +280,7 @@
Here we see that a lot more information is available for developers. Not only is
variable information displayed, but even the exact line numbers of the source
files. This method is the most preferred if you can spare the extra space.
-Here's how much the filesize varies between debug, strip, and -g programs.
+Here's how much the file size varies between debug, strip, and -g programs.
</p>
<pre caption="Filesize differences With -g flag">
@@ -293,8 +293,8 @@
</pre>
<p>
-As you can see, -g adds about a 1000 more bytes to the filesize over the one
-with debugging symbols. However, as shown above, this increase in filesize can
+As you can see, -g adds about a 1000 more bytes to the file size over the one
+with debugging symbols. However, as shown above, this increase in file size can
be worth it if presenting debug information to developers. Now that we have
obtained the backtrace, we can save it to a file by copying and pasting from the
terminal (if it's a non-x based terminal, you can use gpm. To keep this doc
@@ -484,7 +484,7 @@
<body>
<p>
-PORT_LOGDIR is a portage variable that sets up a logdir for individual emerge
+PORT_LOGDIR is a portage variable that sets up a log directory for individual emerge
logs. Let's take a look and see what that entails. First, run your emerge
with PORT_LOGDIR set to your favorite log location. Let's say we have a
location /var/log/portage. We'll use that for our log directory:
@@ -535,9 +535,9 @@
<p>
<uri link="http://www.bugzilla.org">Bugzilla</uri> is what we at Gentoo use to
-handle bugs. Gentoo's Bugzilla is accessible by both https and http. https is
+handle bugs. Gentoo's Bugzilla is accessible by both HTTPS and HTTP. HTTPS is
available for those on insecure networks. For the sake of consistency, I will be
-using the https version in the examples to follow. Head over to <uri
+using the HTTPS version in the examples to follow. Head over to <uri
link="https://bugs.gentoo.org">Gentoo Bugs</uri> to see how it looks.
</p>
@@ -770,13 +770,13 @@
<p>
First, there's the product. This is Gentoo Linux, which we selected earlier.
Component is where the problem occurs. We use this to help us sort out the
-severity of the issue (ie. baselayout and core systems will be more important
+severity of the issue (i.e. baselayout and core systems will be more important
than new ebuilds or application bugs). Here we select Application, as it is an
application at fault. Hardware platform is what architecture you're running.
-If you were running sparc, you would set it to sparc. For this example, we know
+If you were running SPARC, you would set it to SPARC. For this example, we know
this error can occur on multiple architectures, so we'll select All. Operating
System is what Operating System you're using. Because Gentoo is considered a
-"Meta-distribution", it can run on other os's besides Linux. Examples are
+"Meta-distribution", it can run on other OSs besides Linux. Examples are
Gentoo on MacOS, Gentoo on FreeBSD, etc. For this example, we'll select All, as
this can occur on all types of systems. Build Identifier is what is being used
to report the bugs (for logging purposes).You can just leave this as is. Let's
@@ -838,7 +838,7 @@
<p>
Lastly we select the severity of the bug. Please look this over carefully. In
-most cases it's ok to leave it as is and someone will raise/lower it for you.
+most cases it's OK to leave it as is and someone will raise/lower it for you.
However, if you raise the severity of the bug, please make sure you read it over
carefully and make sure you're not making a mistake. Here we will set it to the
default of normal:
@@ -931,7 +931,7 @@
auto. In most cases it's best to manually set it. Our log file is a
plain text file, so we select "plain text (text/plain)". Obsoletes are for when
you are attaching a revision to a previously attached file. You can simply click
-a checkbox next to the old file and Bugzilla will cross it out in the bug,
+a check box next to the old file and Bugzilla will cross it out in the bug,
indicating that the attachment has been obsoleted. Reassignment means you want
to take the bug yourself. I rarely tend to use this.. and I don't think you will
need to at some point (unless you create great patches and we don't care about
@@ -1003,7 +1003,7 @@
<figure link="/images/docs/bugzie-options.png" caption="Bug Options"/>
<p>
-This gives you the option of Reopening the bug if you wish to (ie. the developer
+This gives you the option of Reopening the bug if you wish to (i.e. the developer
thinks it's resolved but it's really not to your standards). Now our bug is
fixed! However, different resolutions can occur. Here's a small list:
</p>
--
gentoo-doc-cvs@gentoo.org mailing list
^ permalink raw reply [flat|nested] 24+ messages in thread
* [gentoo-doc-cvs] cvs commit: bugzilla-howto.xml
@ 2005-07-07 11:24 Shyam Mani
0 siblings, 0 replies; 24+ messages in thread
From: Shyam Mani @ 2005-07-07 11:24 UTC (permalink / raw
To: gentoo-doc-cvs
fox2mike 05/07/07 11:24:54
Modified: xml/htdocs/doc/en/draft bugzilla-howto.xml
Log:
Few more minor changes.
Revision Changes Path
1.2 +26 -26 xml/htdocs/doc/en/draft/bugzilla-howto.xml
file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/bugzilla-howto.xml?rev=1.2&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/bugzilla-howto.xml?rev=1.2&content-type=text/plain&cvsroot=gentoo
diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/bugzilla-howto.xml.diff?r1=1.1&r2=1.2&cvsroot=gentoo
Index: bugzilla-howto.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/bugzilla-howto.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- bugzilla-howto.xml 7 Jul 2005 11:07:05 -0000 1.1
+++ bugzilla-howto.xml 7 Jul 2005 11:24:54 -0000 1.2
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/bugzilla-howto.xml,v 1.1 2005/07/07 11:07:05 fox2mike Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/bugzilla-howto.xml,v 1.2 2005/07/07 11:24:54 fox2mike Exp $ -->
<guide link="/doc/en/bugzilla-howto.xml">
<title>Gentoo Bug Reporting Guide</title>
@@ -187,7 +187,7 @@
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
-There is absolutely no warranty for GDB.sType "show warranty" for details.
+There is absolutely no warranty for GDB. Type "show warranty" for details.
This GDB was configured as "i686-pc-linux-gnu"...Using host libthread_db library "/lib/libthread_db.so.1".
</pre>
@@ -213,7 +213,8 @@
program, making it hard for developers to find which one is causing the issue.
In order to help them out, we do what's called a backtrace. A backtrace runs
backwards through all the functions that occurred upon program execution, to the
-function at fault. To get a backtrace, at the (gdb) prompt, type in <c>bt</c>.
+function at fault. Functions that return (without causing a crash) will not show
+up on the backtrace. To get a backtrace, at the (gdb) prompt, type in <c>bt</c>.
You will get something like this:
</p>
@@ -308,11 +309,11 @@
</pre>
<p>
-This ends the walk-through of gdb. Using gdb, it is my hope that you will be
-able to use it to create better bug reports. However, there are other types of
-errors that can cause a program to fail during run time. One of the other ways
-is through improper file access. We can find those using a nifty little tool
-called <c>strace</c>.
+This ends the walk-through of <c>gdb</c>. Using <c>gdb</c>, I hope that you will
+be able to use it to create better bug reports. However, there are other types
+of errors that can cause a program to fail during run time. One of the other
+ways is through improper file access. We can find those using a nifty little
+tool called <c>strace</c>.
</p>
</body>
@@ -373,10 +374,10 @@
<p>
Aha! So There's the problem. Someone moved the configuration directory to
-.foobar2 instead of .foobar. We also see the program reading in "bar" as it
-should. In this case, we can recommend the ebuild maintainer to put a warning
-about it. For now though, we can copy over the config file from .foobar and
-modify it to produce the correct results.
+<path>.foobar2</path> instead of <path>.foobar</path>. We also see the program
+reading in "bar" as it should. In this case, we can recommend the ebuild
+maintainer to put a warning about it. For now though, we can copy over the
+config file from .foobar and modify it to produce the correct results.
</p>
</body>
@@ -778,7 +779,7 @@
"Meta-distribution", it can run on other os's besides Linux. Examples are
Gentoo on MacOS, Gentoo on FreeBSD, etc. For this example, we'll select All, as
this can occur on all types of systems. Build Identifier is what is being used
-to report the bugs (for logging purposes).sYou can just leave this as is. Let's
+to report the bugs (for logging purposes).You can just leave this as is. Let's
see what we have so far:
</p>
@@ -875,13 +876,12 @@
<figure link="/images/docs/bugzie-new-details.png" caption="New Bug Details"/>
<p>
-Now as you can see, the bug has been assigned to bug-wranglers [at] gentoo
-[dot] org. This is the default location for Application component bugs. However,
-bug-wranglers (usually) won't fix our bugs, so we'll reassign it to someone that
-can (you can let bug-wranglers re-assign it for you as well). For this we use
-the package's metadata.xml. You can normally find them in
-/usr/portage/category/package/metadata.xml. Here's one I've made up for
-foobar2:
+Now as you can see, the bug has been assigned to bug-wranglers@gentoo.org. This
+is the default location for Application component bugs. However, bug-wranglers
+(usually) won't fix our bugs, so we'll reassign it to someone that can (you can
+let bug-wranglers re-assign it for you as well). For this we use the package's
+metadata.xml. You can normally find them in
+/usr/portage/category/package/metadata.xml. Here's one I've made up for foobar2:
</p>
<pre caption="metadata.xml">
@@ -901,21 +901,21 @@
<p>
Notice the maintainer section.T his lists the maintainer of the package, which
-in this case is myself, Chris White. The email listed is chriswhite [at] gentoo
-[dot] org. We will use this to re-assign the bug to the proper person. To do
-this, click the bubble next to Reassign bug to, then fill in the email:
+in this case is myself, Chris White. The email listed is chriswhite@gentoo.org.
+We will use this to re-assign the bug to the proper person. To do this, click
+the bubble next to Reassign bug to, then fill in the email:
</p>
<note>
A package without a metadata.xml file should be re-assigned to
-maintainer-needed [at] gentoo [dot] org.
+maintainer-needed@gentoo.org.
</note>
<figure link="/images/docs/bugzie-reassign.png" caption="Bug Reassignment"/>
<p>
Then hit the Commit button for the changes to take place. The bug has been
-reassigned to me. Shortly afterwards, you notice (by email usually) that I've
+reassigned to me. Shortly afterward, you notice (by email usually) that I've
responded to your bug. I've stated that I'd like to see an strace log to figure
out how the program is trying to access your configuration file. You follow the
previous instructions on using strace and obtain an strace log. Now you need to
@@ -988,7 +988,7 @@
</ul>
<p>
-Now shortly afterward, I find the error in the strace log.sI resolve the bug
+Now shortly afterward, I find the error in the strace log. I resolve the bug
as RESOLVED FIXED and say that there was a change in the location of
configuration files, and that I will update the ebuild with a warning about it.
The bug now becomes resolved, and you are displayed with this:
@@ -1038,7 +1038,7 @@
This concludes the howto on working with Bugzilla. I hope you find this useful.
If you have any questions, comments, or ideas regarding this document, please
send them to me at <mail
-link="chriswhite@gentoo.org">chriswhite [at] gentoo [dot] org</mail>. Special
+link="chriswhite@gentoo.org">chriswhite@gentoo.org</mail>. Special
thanks go to moreon for his notes on -g flags and compile errors, the people at
#gentoo-bugs for helping out with bug-wrangling, and Griffon26 for his notes on
maintainer-needed.
--
gentoo-doc-cvs@gentoo.org mailing list
^ permalink raw reply [flat|nested] 24+ messages in thread
* [gentoo-doc-cvs] cvs commit: bugzilla-howto.xml
@ 2005-07-07 11:07 Shyam Mani
0 siblings, 0 replies; 24+ messages in thread
From: Shyam Mani @ 2005-07-07 11:07 UTC (permalink / raw
To: gentoo-doc-cvs
fox2mike 05/07/07 11:07:05
Added: xml/htdocs/doc/en/draft bugzilla-howto.xml
Log:
#97274 - Testing/Feedback on the doc before going Live.
Revision Changes Path
1.1 xml/htdocs/doc/en/draft/bugzilla-howto.xml
file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/bugzilla-howto.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/bugzilla-howto.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo
Index: bugzilla-howto.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/bugzilla-howto.xml,v 1.1 2005/07/07 11:07:05 fox2mike Exp $ -->
<guide link="/doc/en/bugzilla-howto.xml">
<title>Gentoo Bug Reporting Guide</title>
<author title="Author">
<mail link="chriswhite@gentoo.org">Chris White</mail>
</author>
<author title="Editor">
<mail link="fox2mike@gentoo.org">Shyam Mani</mail>
</author>
<abstract>
This document shows the proper method of reporting bugs using Bugzilla.
</abstract>
<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>
<version>1.0</version>
<date>2005-07-07</date>
<chapter>
<title>Introduction</title>
<section>
<title>Preface</title>
<body>
<p>
Often one of the factors that delay a bug being fixed is how it is reported. By
creating this guide, I hope to help improve the communication between
developers and users in bug resolution. Getting bugs fixed is an important, if
not crucial part of the quality assurance of any project and hopefully this
guide will help make that a success.
</p>
</body>
</section>
<section>
<title>Initial Finding</title>
<body>
<p>
You're emerge-ing a package or working with a program, then suddenly the worst
happens -- you find a bug. Bugs come in many forms, whether it be emerge
failures or segmentation faults. Whatever the cause, the fact still remains that
such a bug must be fixed. Here is a few examples of such bugs.
</p>
<pre caption="A run time error">
$ <i>./bad_code `perl -e 'print Ax100'`</i>
Segmentation fault
</pre>
<pre caption="An emerge failure">
/usr/lib/gcc-lib/i686-pc-linux-gnu/3.3.2/include/g++-v3/backward/backward_warning.h:32:2:
warning: #warning This file includes at least one deprecated or antiquated
header. Please consider using one of the 32 headers found in section 17.4.1.2 of
the C++ standard. Examples include substituting the <X> header for the <X.h>
header for C++ includes, or <sstream> instead of the deprecated header
<strstream.h>. To disable this warning use -Wno-deprecated.
In file included from main.cc:40:
menudef.h:55: error: brace-enclosed initializer used to initialize `
OXPopupMenu*'
menudef.h:62: error: brace-enclosed initializer used to initialize `
OXPopupMenu*'
menudef.h:70: error: brace-enclosed initializer used to initialize `
OXPopupMenu*'
menudef.h:78: error: brace-enclosed initializer used to initialize `
OXPopupMenu*'
main.cc: In member function `void OXMain::DoOpen()':
main.cc:323: warning: unused variable `FILE*fp'
main.cc: In member function `void OXMain::DoSave(char*)':
main.cc:337: warning: unused variable `FILE*fp'
make[1]: *** [main.o] Error 1
make[1]: Leaving directory
`/var/tmp/portage/xclass-0.7.4/work/xclass-0.7.4/example-app'
make: *** [shared] Error 2
!!! ERROR: x11-libs/xclass-0.7.4 failed.
!!! Function src_compile, Line 29, Exitcode 2
!!! 'emake shared' failed
</pre>
<p>
These errors can be quite troublesome. However, once you find them, what do
you do? The following sections will look at 2 important tools for handling
run time errors. After that, we'll take a look at compile errors, and how to
handle them. Let's start out with the first tool for debugging run time
errors -- <c>gdb</c>
</p>
</body>
</section>
</chapter>
<chapter>
<title>Debugging using GDB</title>
<section>
<title>Introduction</title>
<body>
<p>
GDB, or the (G)NU (D)e(B)ugger, is a program used to find run time errors that
normally involve memory corruption. First off, let's take a look at what
debugging entails. One of the main things you must do in order to debug a
program is to <c>emerge</c> the program with FEATURES="nostrip". This prevents
the stripping of debug symbols. Why are programs stripped by default? The reason
is the same as that for having gzipped man pages -- saving space. Here's how the
size of a program varies with and without debug symbol stripping.
</p>
<pre caption="Filesize Comparison">
<comment>(debug symbols stripped)</comment>
-rwxr-xr-x 1 chris users 3140 6/28 13:11 bad_code
<comment>(debug symbols intact)</comment>
-rwxr-xr-x 1 chris users 6374 6/28 13:10 bad_code
</pre>
<p>
Just for reference, <e>bad_code</e> is the program we'll be debugging with
<c>gdb</c> later on. As you can see, the program without debugging symbols is
3140 bytes, while the program with them is 6374 bytes. That's close to double
the size! Two more things can be done for debugging. The first is adding -g to
your CFLAGS and CXXFLAGS. This flag adds more debugging information than is
generally included. We'll see what that means later on. Lastly, you can also add
debug to the package's USE flags. This can be done with the
<path>package.use</path> file.
</p>
<pre caption="Using package.use to add debug USE flag">
# <i>echo "category/package debug" >> /etc/portage/package.use</i>
</pre>
<note>
The directory <path>/etc/portage</path> does not exist by default and you may
have to create it, if you have not already done so. If the package already has
USE flags set in <path>package.use</path>, you will need to manually modify them
in your favorite editor.
</note>
<p>
Now that that's done, you will need to re-emerge your package to set the
new debug settings into place. This can be done as follows:
</p>
<pre caption="Re-emergeing a package with debugging">
# <i>FEATURES="nostrip" emerge package</i>
</pre>
<p>
Now that debug symbols are setup, we can continue with debugging the program.
</p>
</body>
</section>
<section>
<title>Running the program with GDB</title>
<body>
<p>
Let's say we have a program here called "bad_code" (I know, it's sort of cheesy
but..). Some person claims he can break the code and provides an example. You go
ahead and test it out:
</p>
<pre caption="Breaking The Program">
$ <i>./bad_code `perl -e 'print Ax100'`</i>
Segmentation fault
</pre>
<p>
It seems this person was right. Since the program is obviously broken, we have
a bug at hand. Now, it's time to use <c>gdb</c> to help solve this matter. First
we run <c>gdb</c> with <c>--args</c>, then give it the full program with
arguments like shown:
</p>
<pre caption="Running Our Program Through GDB">
$ <i>gdb --args ./bad_code `perl -e 'print Ax100'`</i>
GNU gdb 6.3
Copyright 2004 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB.sType "show warranty" for details.
This GDB was configured as "i686-pc-linux-gnu"...Using host libthread_db library "/lib/libthread_db.so.1".
</pre>
<p>
You should see a small terminal like setup after that which says "(gdb)" and
waits for input. First, we have to run the program. We type in <c>run</c> at the
command and receive a notice like:
</p>
--
gentoo-doc-cvs@gentoo.org mailing list
^ permalink raw reply [flat|nested] 24+ messages in thread
end of thread, other threads:[~2008-05-23 20:42 UTC | newest]
Thread overview: 24+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2007-04-01 10:35 [gentoo-doc-cvs] cvs commit: bugzilla-howto.xml Josh Saddler
-- strict thread matches above, loose matches on Subject: below --
2008-05-23 20:42 Sven Vermeulen
2008-02-01 19:30 Jan Kundrat
2008-01-31 21:33 Jan Kundrat
2008-01-31 14:31 Jan Kundrat
2007-02-14 21:30 Josh Saddler
2006-11-10 22:19 Josh Saddler
2006-09-02 5:26 Lukasz Damentko
2005-09-29 15:11 Xavier Neys
2005-08-30 2:51 vapier
2005-07-22 23:46 Xavier Neys
2005-07-13 5:48 Shyam Mani
2005-07-10 14:13 Shyam Mani
2005-07-09 22:31 Shyam Mani
2005-07-07 18:19 Shyam Mani
2005-07-07 12:03 Shyam Mani
2005-07-07 12:02 Shyam Mani
2005-07-07 11:56 Sven Vermeulen
2005-07-07 11:55 Shyam Mani
2005-07-07 11:47 Sven Vermeulen
2005-07-07 11:38 Sven Vermeulen
2005-07-07 11:35 Sven Vermeulen
2005-07-07 11:24 Shyam Mani
2005-07-07 11:07 Shyam Mani
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox