Attachment 77689 Details for Bug 102194 – bugzilla-howto.xml

bugzilla-howto.xml

bugzilla-howto.xml (text/plain), 19.23 KB, created by Chris White (RETIRED) on 2006-01-21 02:19:53 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Chris White (RETIRED)

Created: 2006-01-21 02:19:53 UTC

Size: 19.23 KB

patch

obsolete

><?xml version="1.0" encoding="UTF-8"?>
><!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
>
>
><guide link="/doc/en/guide.xml" lang="en">
><title>Gentoo Documentation Guide</title>
>
><author title="Author">
>  <mail link="chriswhite@gentoo.org">Chris White</mail>
></author>
>
><abstract>
>This guide is meant to introduce the proper procedures for filling bug reports
>to the Gentoo Bugzilla bug reporting system.
></abstract>
>
>
>
><license/>
>
><version>2.0</version>
><date>2006-01-20</date>
>
><chapter>
><title>Introduction</title>
><section>
><title>What Are Bugs?</title>
><body>
>
><p>
>Bugs are a flaw in a piece of software that somehow inhibits the ability to use
>the software. This can occur in two forms, the first being a compile bug, and
>the second being a runtime bug. Generally compile time bugs are more critical,
>as they prevent the user from installing the software. This guide is meant to
>show how to report these issues, and help to resolve them. The next section will
>introduce the Gentoo Bugzilla homepage, as well as a few of the features it provides.
></p>
>
></body>
></section>
><section>
><title>The Bugzilla Homepage</title>
><body>
>
><p>
>To start off, the Gentoo Bugzilla homepage can be found <uri
>link="https://bugs.gentoo.org">here</uri>. The page will show a few features
>right away. These include:
></p>
>
><ul>
>  <li>View Bugs Reported Today</li>
>  <li>Search existing bug reports</li>
>  <li>Advanced search of existing reports</li>
>  <li>Enter a new bug report</li>
>  <li>Summary reports and charts</li>
></ul>
>
><p>
>This document will cover the <c>Advanced search of existing reports</c> and <c>Enter a
>new bug report</c> features.  <c>Search existing bug reports</c> generally proves to be
>somewhat insufficient for providing the best results. <c>View Bugs Reported
>Today</c> is mostly for those who wish to contribute more to bugzilla.  It simply
>provides the functionality of seeing what new bugs have been added for the day.
><c>Summary reports and charts</c> is an advanced functionality that is somewhat
>infrequently used. The information provided by <c>Advanced search of bug
>reports</c> is generally sufficient for such purposes. However, as a word of
>warning, unless you register your account through the <c>Open a new Bugzilla
>account</c> below the login form, you will only be able to search for and view
>bugs. The most important of these functions is the <c>Advanced search of
>existing reports</c>.  This next chapter will explore its usage and how to
>achieve manageable results.
></p>
>
></body>
></section>
></chapter>
><chapter>
><title>Searching For Bugs</title>
><section>
><title>Preparing The Search Query</title>
><body>
>
><p>
>In order to achieve a successful search query, it is important to know what
>information you need ahead of time. First off is the preparation of searching
>through compile error bugs. Compile error bugs are one of the most commonly
>duplicated bugs. This is often attributed to the fact that it prevents users
>from getting a package installed, and are of high importance in getting fixed.
>However it is often underestimated that the issue has already been solved. This
>may have a lot of reasons, but one of them is the inhibited abilities of a
>simple bug search. These inhibited abilities include:
></p>
>
><ul>
>  <li>
>    It only searches open bugs. If the issue is promptly fixed,
>    a user will not see it.
>  </li>
>  <li>
>    It will only search summaries. Searching by summary keywords is often
>    difficult, and the keywords to achieve the required results are a hit and miss
>    at best.
>  </li>
>  <li>
>    Because of the nonspecific nature of the search, something such as "qt"
>    being entered will cause a large overflow of results, something that the user
>    will not be able to handle quite as efficiently.
>  </li>
></ul>
>
><p>
>To begin, bring up the advanced search form through the link on the front page,
>or by <uri link="https://bugs.gentoo.org/query.cgi">clicking here</uri>. This
>brings up the advanced search page, where quite a bit of options are presented.
>While it may seem daunting at first, focus needs only be directed towards a few
>of the form inputs. The following table presents these inputs, and what should
>be entered in them. It looks at the differences and similarities between runtime
>and 
></p>
>
><table>
><tr>
>  <th colspan="2">Search Field Options</th>
></tr>
><tr>
>  <ti>Summary</ti>
>  <ti>
>    The summary field will hold the name of the package. This is meant to be as
>    non-specific as possible, and is enhanced by the other fields.
>  </ti>
></tr>
><tr>
>  <ti>Comment</ti>
>  <ti>
>    The comment field will hold the relevant information. Generally just the !!!
>    error string with the version is sufficient.  An example is:
>    <c>!!! ERROR: x11-libs/qt-3.1.1-r1 failed.</c>. If this produces more bug
>    reports, it's generally recommended to get more specific by providing the
>    exact error string. An example of that is: <c>make[1]: ***
>    [../lib/libqt-mt.so.3.1.1] Error 1</c>. If this is a runtime error, it's
>    best to try and search by the package name, version, and any error message
>    that comes out. If have a backtrace, search by at least 3 of the backtrace
>    messages.
>  </ti>
></tr>
><tr>
>  <ti>Status</ti>
>  <ti>
>    The status field should have all its entries marked. If this is not done,
>    and the bug you wish to find is closed (not one of the defaults), you will
>    not be able to find it. This is the one place where it's not a good idea to
>    leave out certain options.
>  </ti>
></tr>
><tr>
>  <ti>Resolution</ti>
>  <ti>
>    Every option <e>except</e> DUPLICATE should be marked. Duplicate bugs may
>    provide you with what you're looking for, but they really just clutter the
>    results.
>  </ti>
></tr>
></table>
>
><p>
>Now that it's clear how to go about searching, the next section will go into
>handling the results.
></p>
>
></body>
></section>
><section>
><title>Handling The Search Results</title>
><body>
>
><p>
>Now that the proper query is setup, it is now time to analyze the search
>results presented. Take the example compiler error string presented above. Go
>ahead and setup the summary to <c>qt</c>, the comment to <c>!!! ERROR:
>x11-libs/qt-3.1.1-r1 failed.</c>, the status to all possible types, and the
>resolution to everything but <c>DUPLICATE</c>. Also make sure the box next to
>the comment field contains <c>contains all of the words/strings</c>. The results
>come to a surprisingly accurate one result:
></p>
>
><ul>
>  <li>ID    Sev Pri Plt Assignee       Status Resolution Summary</li>
>  <li>14904 nor P2  x86 kde@gentoo.org RESO   FIXE       qt 3.1.1-r1 won't compile.</li>
></ul>
>
><p>
>Upon further analysis of the bug, it does indeed contain the comment line used
>in the comment field, and with only one result it's easy to handle. Now, in
>order to show the effectiveness of this method, try the same as above, but do
>not input anything into the comment field. Now in this case, the bug was found.
>However, this is not always the case. If you didn't find your bug, it needs to
>be reported and resolved as quickly as possible. The next chapter will look at
>reporting your bug.
></p>
>
></body>
></section>
></chapter>
><chapter>
><title>Reporting Bugs</title>
><section>
><title>Where To File</title>
><body>
>
><p>
>To start reporting your bug, click on <c>Enter a new bug report</c> on the front
>page, or <uri link="https://bugs.gentoo.org/enter_bug.cgi">click here</uri>. 
>Please note that this requires a registered and logged-in account.
></p>
>
><p>
>This displays the first page of the new bug report process. This was originally
>a 2-3 step process, depending on what method was selected. However it has now
>been altered to only use a two step bug reporting system. The first step is to
>select where this ebuild will go. This is often a daunting process, and has a
>few misguided assumptions around it. These include:
></p>
>
><ul>
>  <li>
>    Portage Development - It is assumed that because a package exists in the
>    portage tree, it is the duty of the portage team to handle the bug. This is
>    an incorrect assumption. The portage team handles the inner functionality of
>    portage itself. <b>General ebuild bugs do not go here</b>.
>  </li>
>  <li>
>    Gentoo Infrastructure - Infrastructure handles the servers that serve the
>    portage tree, therefore they are responsible for it. This is once again an
>    incorrect assumption. Further more, there are members of infrastructure that
>    are not portage tree developers. Despite their direct access to the portage
>    tree, they will not touch it in less of rare emergencies. <b>General ebuild
>    bugs do not go here</b>.
>  </li>
></ul>
>
><p>
>General ebuild bugs should go to the <c>Gentoo Linux</c> product. In fact, it's
>often hard to find bugs that don't belong there. This is the most widely used
>product in bugzilla. Now that a filing location has been established, the next
>section will go into the actual filing of the bug.
></p>
>
></body>
></section>
><section>
><title>Submitting The Information</title>
><body>
>
><p>
>The presented screen for bug entry is somewhat simple. As with the advanced
>search page, focus needs only be directed towards a few important fields.
></p>
>
><table>
><tr>
>  <th colspan="2">Bug Entry Fields</th>
></tr>
><tr>
>  <ti>Component</ti>
>  <ti>
>    The actual meanings of the different components can be found <uri
>    link="https://bugs.gentoo.org/describecomponents.cgi?product=Gentoo%20Linux">here</uri>.
>    These descriptions are fairly straightforward, and will give you an idea of
>    where to put it. As it says, if you are unsure, simply use the
>    <c>Unspecified</c> component.
>  </ti>
></tr>
><tr>
>  <ti>URL</ti>
>  <ti>
>    This field should show any URL that embodies the core of the bug. A <e>large
>    mistake</e> that is often made is to point directly to forums postings.
>    <e>Do not do this!</e>. To make things more organized, please present the
>    information in full in the bug report itself. This will let the developer
>    know the exact point you are trying to express with your bug. Generally this
>    field should be used to point to homepages of new ebuilds, or mailing list
>    threads regarding the bug. If it is a log or a patch, please use the
>    attachment that will be discussed later on. This keeps things in one place
>    for better organization.
>  </ti>
></tr>
><tr>
>  <ti>Summary</ti>
>  <ti>
>    This is where the bug should be briefly described. For example, using the
>    previously mentioned qt error, something like this would be sufficient:
>    <c>x11-libs/qt-3.1.1-r1 compile fails with libqt-mt error</c>. The summary
>    contains both the package name and version, as well as a small description
>    of what is causing the error (libqt-mt compiling).
>  </ti>
></tr>
><tr>
>  <ti>Description</ti>
>  <ti>
>    This is where you describe the bug. If your build error is around 5-7 lines,
>    it's ok to paste it here. If it's fairly long, attach it as described later.
>    You must also add your <c>emerge --info</c> output as well.
>  </ti>
></tr>
></table>
>
><note>
>If the <c>emerge --info</c> output contains modifications to variables such as
><c>LDFLAGS</c> or <c>ASFLAGS</c> they will most likely be invalidated. Also bugs
>with very long CFLAGS will have the same issue. Unless you can prove without a
>doubt why it should work, it's not a good idea to post a bug.
></note>
>
><p>
>Now that the bug is ready, it can be committed. This will produce a confirmation
>screen with the new bug report and its bug number. The bug number is what will
>be used to reference to the bug later on. Now that the bug report is submitted,
>it will await developer action. The next chapter will discuss the lifetime of
>your bug report.
></p>
>
></body>
></section>
></chapter>
><chapter>
><title>Working With Your Bug</title>
><section>
><title>Bug Assignment</title>
><body>
>
><p>
>When a bug is submitted, it will usually be assigned within a reasonable time
>period. Assignment is the process by which a bug wrangler (someone that handles
>where bugs go) will attach the bug to a developer. The developer will then take
>the appropriate action to resolve the bug. However, with the case of ebuilds and
>packages without a maintainer, they will go to
><c>maintainer-wanted@gentoo.org</c> or <c>maintainer-needed@gentoo.org</c>. In
>the case of maintainer-wanted, the bug is a new ebuild that doesn't have an
>obvious person to take the package up. These bugs are generally checked by
>someone for ebuild sanity, then possibly picked up later on. The
>maintainer-needed bugs are bugs for packages left over by retired maintainers.
>These type of bugs generally have more priority over maintainer-wanted, as they
>are for package that already exist in the tree. Once the bug is assigned, the
>developer may respond asking for more information, such as debug output or other
>files. Sometimes the <c>emerge</c> error will even tell you to attach a 
>config.log file. This next section will look at how to attach files to bugs.
></p>
>
></body>
></section>
><section>
><title>Attaching Files To Bugs</title>
><body>
>
><p>
>In order to attach a file to a bug, you must first have already reported the
>bug, and must be present at your bug report screen. You can reach your bug
>report by entering <c>https://bugs.gentoo.org/[bugnumber]</c> into your browser.
>At the bug report screen, you will notice a <c>Create a New Attachment</c> link.
>Click on that to start the process.
></p>
>
><p>
>At the attachment screen, you will be asked to fill out information regarding
>the attachment. The fields are described below.
></p>
>
><table>
><tr>
>  <th colspan="2">Attachment Fields Description</th>
></tr>
><tr>
>  <ti>File</ti>
>  <ti>
>    This field doesn't require much description. The file you wish to attach is
>    entered here, either by the pathname, or browsing for it with the browse
>    button.
>  </ti>
></tr>
><tr>
>  <ti>Description</ti>
>  <ti>
>    This describes what the patch is. In general I usually set this to the
>    filename without the path.
>  </ti>
></tr>
><tr>
>  <ti>Content Type</ti>
>  <ti>
>    In this area, you are presented with two options, the first being to declare
>    the file as a patch, the second being to declare it as another type of file.
>    The most submitted filetypes are ebuilds, patches, and logs. Patches have
>    their own checkbox to easily setup the content type. If it's an ebuild, log,
>    or other text file, choose <c>select from list</c> and leave it at text/plain.
>    <e>NEVER</e> select autodetect! It is known to turn ebuilds into binary
>    files, and causes a general hassle when viewing the file. If it's something
>    like a tarball or archive of some sort, choose <c>select from list</c> and
>    set the type to <c>binary file (application/octet-stream)</c>.
>  </ti>
></tr>
><tr>
>  <ti>Obsoletes</ti>
>  <ti>
>    If the file you are attaching is an update to another file, simply click the
>    checkbox next to it to obsolete it. This will cause the obsoleted file to
>    showup crossed out in the attachment section of the bug report. This is very
>    handy in the case of a large number of attachments. It lets the developer
>    focus on what attachment actually needs their attention.
>  </ti>
></tr>
><tr>
>  <ti>Comment</ti>
>  <ti>
>    If you'd like to describe your attachment in fuller detail, use this entry
>    field to do so.
>  </ti>
></tr>
></table>
>
><p>
>Now that that file attachment has occurred, the developer can use the information
>to further along the bug. While the bug is being worked on, other people might
>want to track it, or you might have stumbled across the bug during the search
>phase. The next section will discuss how to cc someone to a bug.
></p>
>
></body>
></section>
><section>
><title>Using CC-ing To Follow A Bug</title>
><body>
>
><p>
>When tracking a bug, one can use the bug number, or bookmark their bug. However,
>a more convenient way to track a bug is by CC'ing yourself, or another person onto
>the bug.
></p>
>
><p>
>Bugzilla can do two types of CC's. The first is to CC yourself to the bug, the
>second is to CC others to the bug. In order to CC yourself to a bug, click on
>the <c>Add (email here) to CC list</c> below the <c>Additional Comments</c>
>field. You can add other bugzilla members to a bug as well. To do so, enter
>their name(s) in the <c>Add CC</c> field below the report name. For multiple
>email addresses, separate them with a space or comma. By CC'ing yourself or
>another person to a bug, they will be emailed whenever the bug is updated. This
>provides an easy and efficient way to track the bug. Once the developer has the
>information needed, they will <c>RESOLVE</c> the bug. The next section will
>describe the different types of resolutions.
></p>
>
></body>
></section>
><section>
><title>Bug Resolutions</title>
><body>
>
><p>
>A bug can be resolved in a number of ways. The table below describes some of the
>ways that developers can resolve a bug:
></p>
>
><table>
><tr>
>  <th colspan="2">Resolution Types</th>
></tr>
><tr>
>  <ti>FIXED</ti>
>  <ti>
>    In this case, the developer is stating that the bug was taken care of. If by
>    an ebuild update, you will normally have to wait about an hour to an hour an
>    a  half until the ebuild is reachable by <c>emerge --sync</c>.
>  </ti>
></tr>
><tr>
>  <ti>INVALID</ti>
>  <ti>
>    The developer sees something wrong specifically with your setup. This is
>    generally used for bugs with previously mentioned altered
>    <c>LDFLAGS</c>,<c>ASFLAGS</c>, or <c>CFLAGS</c>.
>  </ti>
></tr>
><tr>
>  <ti>WONTFIX</ti>
>  <ti>
>    Because of some sort of situation, the developer will not fix the bug. This
>    is generally seen with feature requests that are unreasonable.
>  </ti>
></tr>
><tr>
>  <ti>LATER</ti>
>  <ti>
>    The developer is usually waiting on action from other bugs, or wants to wait
>    for another release before implementing a feature. This is infrequently
>    used.
>  </ti>
></tr>
><tr>
>  <ti>REMIND</ti>
>  <ti>
>    From a personal perspective, I've never seen this used. It was implemented
>    to help developers reminds themselves about certain features, but most are
>    able to track things enough not to use this.
>  </ti>
></tr>
><tr>
>  <ti>WORKSFORME</ti>
>  <ti>
>    The developer is unable to reproduce the bug, and no one else is able to
>    confirm it. If your bug is resolved as this, and you believe it's still
>    valid, it's best to get another person to verify your issue and comment on
>    the bug.
>  </ti>
></tr>
><tr>
>  <ti>CANTFIX</ti>
>  <ti>
>    Something out of the hands of the developer prevents them from fixing the
>    bug. This may be the way upstream does something, or another issue of that
>    sort.
>  </ti>
></tr>
><tr>
>  <ti>NEEDINFO</ti>
>  <ti>
>    This is generally used for cases when the developer needs <c>emerge
>    --sync</c> output, or any other information relevant to getting the bug
>    fixed.
>  </ti>
></tr>
><tr>
>  <ti>TEST-REQUEST</ti>
>  <ti>
>    This is used when a user is presented with something to test, and don't
>    respond for a long period of time.
>  </ti>
></tr>
><tr>
>  <ti>UPSTREAM</ti>
>  <ti>
>    Upstream is what is used to refer to the actual developers of the package.
>    If something is resolved as UPSTREAM, it means that the developer can do
>    nothing about it unless upstream developers respond, or they would rather
>    see upstream apply a new feature/patch before accepting it.
>  </ti>
></tr>
></table>
>
><p>
>This completes the Gentoo Bugzilla reporting guide. Thanks to everyone that
>helped complete it, and I hope it turns out into a highly useful tool for
>people reporting bugs. If you have questions or comments regarding this
>document, please send them to <email>chriswhite@gentoo.org</email>.
></p>
>
></body>
></section>
></chapter>
></guide>

Actions: View

Attachments on bug 102194: 65727 | 77689 | 77741