Introduction
What Are Bugs?
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.
The Bugzilla Homepage
To start off, the Gentoo Bugzilla homepage can be found here. The page will show a few features
right away. These include:
- View Bugs Reported Today
- Search existing bug reports
- Advanced search of existing reports
- Enter a new bug report
- Summary reports and charts
This document will cover the Advanced search of existing reports and Enter a
new bug report features. Search existing bug reports generally proves to be
somewhat insufficient for providing the best results. View Bugs Reported
Today 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.
Summary reports and charts is an advanced functionality that is somewhat
infrequently used. The information provided by Advanced search of bug
reports is generally sufficient for such purposes. However, as a word of
warning, unless you register your account through the Open a new Bugzilla
account below the login form, you will only be able to search for and view
bugs. The most important of these functions is the Advanced search of
existing reports. This next chapter will explore its usage and how to
achieve manageable results.
Searching For Bugs
Preparing The Search Query
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:
-
It only searches open bugs. If the issue is promptly fixed,
a user will not see it.
-
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.
-
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.
To begin, bring up the advanced search form through the link on the front page,
or by clicking here. 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
| Search Field Options |
Summary
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.
Comment
The comment field will hold the relevant information. Generally just the !!!
error string with the version is sufficient. An example is:
!!! ERROR: x11-libs/qt-3.1.1-r1 failed.. 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: make[1]: ***
[../lib/libqt-mt.so.3.1.1] Error 1. 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.
Status
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.
Resolution
Every option except DUPLICATE should be marked. Duplicate bugs may
provide you with what you're looking for, but they really just clutter the
results.
Now that it's clear how to go about searching, the next section will go into
handling the results.
Handling The Search Results
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 qt, the comment to !!! ERROR:
x11-libs/qt-3.1.1-r1 failed., the status to all possible types, and the
resolution to everything but DUPLICATE. Also make sure the box next to
the comment field contains contains all of the words/strings. The results
come to a surprisingly accurate one result:
- ID Sev Pri Plt Assignee Status Resolution Summary
- 14904 nor P2 x86 kde@gentoo.org RESO FIXE qt 3.1.1-r1 won't compile.
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.
Reporting Bugs
Where To File
To start reporting your bug, click on Enter a new bug report on the front
page, or click here.
Please note that this requires a registered and logged-in account.
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:
-
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. General ebuild bugs do not go here.
-
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. General ebuild
bugs do not go here.
General ebuild bugs should go to the Gentoo Linux 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.
Submitting The Information
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.
| Bug Entry Fields |
Component
The actual meanings of the different components can be found here.
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
Unspecified component.
URL
This field should show any URL that embodies the core of the bug. A large
mistake that is often made is to point directly to forums postings.
Do not do this!. 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.
Summary
This is where the bug should be briefly described. For example, using the
previously mentioned qt error, something like this would be sufficient:
x11-libs/qt-3.1.1-r1 compile fails with libqt-mt error. The summary
contains both the package name and version, as well as a small description
of what is causing the error (libqt-mt compiling).
Description
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 emerge --info output as well.
If the emerge --info output contains modifications to variables such as
LDFLAGS or ASFLAGS 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.
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.
Working With Your Bug
Bug Assignment
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
maintainer-wanted@gentoo.org or maintainer-needed@gentoo.org. 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 emerge error will even tell you to attach a
config.log file. This next section will look at how to attach files to bugs.
Attaching Files To Bugs
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 https://bugs.gentoo.org/[bugnumber] into your browser.
At the bug report screen, you will notice a Create a New Attachment link.
Click on that to start the process.
At the attachment screen, you will be asked to fill out information regarding
the attachment. The fields are described below.
| Attachment Fields Description |
File
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.
Description
This describes what the patch is. In general I usually set this to the
filename without the path.
Content Type
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 select from list and leave it at text/plain.
NEVER 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 select from list and
set the type to binary file (application/octet-stream).
Obsoletes
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.
Comment
If you'd like to describe your attachment in fuller detail, use this entry
field to do so.
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.
Using CC-ing To Follow A Bug
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.
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 Add (email here) to CC list below the Additional Comments
field. You can add other bugzilla members to a bug as well. To do so, enter
their name(s) in the Add CC 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 RESOLVE the bug. The next section will
describe the different types of resolutions.
Bug Resolutions
A bug can be resolved in a number of ways. The table below describes some of the
ways that developers can resolve a bug:
| Resolution Types |
FIXED
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 emerge --sync.
INVALID
The developer sees something wrong specifically with your setup. This is
generally used for bugs with previously mentioned altered
LDFLAGS,ASFLAGS, or CFLAGS.
WONTFIX
Because of some sort of situation, the developer will not fix the bug. This
is generally seen with feature requests that are unreasonable.
LATER
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.
REMIND
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.
WORKSFORME
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.
CANTFIX
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.
NEEDINFO
This is generally used for cases when the developer needs emerge
--sync output, or any other information relevant to getting the bug
fixed.
TEST-REQUEST
This is used when a user is presented with something to test, and don't
respond for a long period of time.
UPSTREAM
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.
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 chriswhite@gentoo.org.