The Bug Wranglers Project
The Gentoo Bug Wranglers project controls and describes the tasks to be carried
out and goals to be achieved for everyone who wrangles bugs on Gentoo's bug tracker.
The project was set up after the de facto resignation of long time Main
Bug Wrangler Jakub Moc, when it turned out we required a division of labour
to get all bugs properly assigned within an acceptable timeframe (from the
moment of a bug report's creation to its proper assignment). For his years of
relentless bug wrangling, this project both owes him its gratitude and earns
The project strives to get every bug assigned within a day, counting from
the moment when enough information has been gathered. In the future, the
project's aims are to credit developers and users who help out, to maintain a
list of notable bug wranglers, and to gather yet more useful guidelines on this
The goal of the Bug Wranglers project is to clarify how new bugs on
Gentoo's bug tracker should be handled. This document describes the rules to
bug assignment, CC'ing herd teams, maintainers, the role of metadata.xml and
who are bug wranglers and how one should contact them.
|Stephanie J. Lockwood-Childs
All developers can be reached by e-mail using firstname.lastname@example.org.
We are currently looking for users interested in helping the project with
the following jobs:
- Job description
Gentoo needs more people handling new bugs (i.e. assigning them
to the right people, making sure the reporter has submitted enough info,
Good understanding of Gentoo and Bugzilla, always respecting the users.
Assessing Bug Reports
How and when you assign a bug report depends on the type of bug report as well as
correctness and completeness of the bug report.
Bug reports requesting version bumps should be assigned to
the appropriate maintainers directly. Also check the description of the
bug for references to security bugs, in which case the bug report should
be assigned to email@example.com
immediately, using product "Gentoo Security" and component "Vulnerabilities",
with the maintainers CC'd.
Bug reports that say something isn't working or compiling without a
comprehensive analysis of the causes, should contain at least the output of
`emerge --info' as well as a thorough description of the problem, including
error output (or expected versus actual output), the command that led to the
error or faulty output, and concise steps explaining how to reproduce the
issue. It is customary to only assign a bug report once these requirements have
been fulfilled. If the reporter hasn't fulfilled these requirements, the bug
should be marked ASSIGNED to bug-wranglers, and a full build log should
be requested from the reporter.
Bug reports that include patches or other solutions accompanying
the actual bug description can usually be assigned directly to the maintainers.
The Summary uniquely identifies the bug that is being reported. As
there could be several bugs saying that cat/pkg "failed to emerge", it is
important to at least replace such generic descriptions of an emerge failing
with a more exact description, noting the ebuild phase that failed or, better
yet, the first error message that occured.
Bug reports that refer to a single or a few (similar) packages should
detail the package atom(s) as completely as possible (at least the
CATEGORY/PKG(s)) at the start of the Summary. If the ebuild is from an
overlay, the name of the overlay should be prefixed at the start in square
brackets. The atom should include a version only when other versions do not
exhibit the bug. Also note that CATEGORY/PKG[-VERSION].ebuild is never a valid
atom - either refer to CATEGORY/PKG/PKG[-VERSION].ebuild or simply remove the
.ebuild suffix entirely.
Code Listing 5.1: The standard format of the Summary
[name overlay] CATEGORY/PKG(-version(-revision)) - problem description
Bug reports about eclasses should list the full eclass filename in the
Summary instead of an atom.
Acquiring More Information (and when not to)
Bug reports can quickly get messy from comments and attachments that may or
may not be appropriate to the bug being reported. Handing over such bug reports
to the proper assignees is not much fun, and you cannot delete comments or
attachments that aren't any use (although you can mark the latter as obsolete
if need be). Since you cannot filter out the information you ultimately hand
over to the assignee, you will have to make sure you don't just ask for the
right information, but ask it in the best possible way. Sometimes, it is
necessary to request that no more information is added. In general, be gentle
in your verbal assessment of a bug report. Even if you are quite certain that
it's going to be resolved as INVALID, you should treat the reporter
- If you find that a reported problem arose because the reporter lacks
certain skills or knowledge, then provide the so-called 'obvious' solution
to the problem and suggest that he might try that. It is unnecessary to explain
that you consider the reported problem not to be a bug. Just resolve the bug
with a TEST-REQUEST (instead of as INVALID) and suggest that the
reporter tests the solution you provide, and that he reopens the bug only when
that doesn't solve the problem.
- Assume that the reporter can help but may not know how, without either
suggesting he may not know how or assuming he does know how. In practice, that
means you provide the commands that produce the information you require.
Do so even if the means to that end seem trivial, like asking for `emerge
--info' or `emerge -vp cat/pkg'.
- Do not assume that the reporter ought to know how to report bugs. An
omitted `emerge --info' does not call for a public flogging, it simply calls
for the missing `emerge --info'. Even experienced reporters make mistakes, so
simply request the information, mark the bug as ASSIGNED and wait for
the information you requested.
- Bug reports should be concise, as all too quickly they bog down and can
be best understood after reading, say, nothing but comment #1, #2 and #7,
ignoring all 40 intermediate and later comments which are the me-toos and
not-mes (including lots of `emerge --info' and/or hardware collection lists
that may or may not be relevant). When enough information has been
presented to 'make a case', it's appropriate to say so.
- Some bugs make your blood boil. Ignore them and let someone else handle
Assigning Bug Reports
To assign a bug report to the right people, you will need to find some more
information, depending on the type of bug report.
If a bug report pertains to a specific package, then you enter the
package's directory in your copy of the gentoo-x86 CVS
repository (or perhaps the online version which should always be more or
less up to date) and read the metadata.xml file you find there. When
metadata.xml lists a single maintainer or herd, then you assign the bug
to that maintainer or herd. When the file lists multiple entries, then you
assign the bug to the first <maintainer>, and CC the other
<maintainer>(s) and <herd>(s). If you find that metadata.xml
lists inappropriate and/or confusing contact information, then make a note of
that in a comment on the bug report and assign/CC the bug report as best as
In cases where metadata.xml lists a herd which Gentoo Bugzilla
doesn't know about (which it will ask you to correct before it accepts changes
to the bug report), you should consult herds.xml to figure out the
appropriate e-mail alias for that herd.
When a bug report calls attention to multiple packages, then things
get slightly more complicated. When the listed packages do not belong to the
same maintainer or team, for instance when a library upgrade causes several
packages to fail to emerge or run, then you should ask the bug reporter to file
separate bugs assigned to each set of packages' maintainer(s), and make those
bug reports block the original bug report, which then becomes a tracker
bug (denoted by the Tracker keyword. Bug reports with many
maintainers CC'd are known to bog down and never get resolved. Of course, you
should only create a tracker bug when the bug is confirmed and the solution is
Bug reports that concern eclasses should be assigned to the eclass
maintainer. To figure out who maintains an eclass, browse to the
directory, open the file and read who maintains the eclass at the top of the
file. When an eclass file does not list maintainers, the bug report should
note this omission and the last committer to that file should be made the
A keyword request should be assigned to the package's maintainer and
CC'd to the appropriate arch team(s). The report's Keywords field should
contain the KEYWORDREQ keyword.
A stabilisation request should be handled by the package's maintainer, so
you should not CC arch teams in your role as bug wrangler, nor set the
STABLEREQ keyword in the Keywords field. Unless the package is
maintainer-needed, then you should add arches and set the Keyword field if the
bug makes sense.
Bug reports that concern profiles should be assigned to
firstname.lastname@example.org CC'd. Exceptions
are profiles that are obviously maintained by some herd, like hardened, selinux,
prefix, etc. Those get assigned to the maintaining herd.
Bug reports that relate to issues other than the portage tree, like
problems with Gentoo's bugzilla, Gentoo infrastructure, mirrors or staffing
matters (devrel, userrel and so on) are usually easier to assign. The
Product and Component fields of each bug should help you
(re)assign these reports appropriately.
All Gentoo developers who can change the Assignee fields of new bugs are
welcome to help assign bugs to the right developers. Most assignees will
appreciate it if, in doing so, you follow the rules layed out above.
Users are encouraged to assist in wrangling bugs as well. Even without bugzilla
privileges you can help by reproducing bugs and posting additional information
The best approach to bug wrangling is to really get involved with
individual bug reports. Do not wrangle bugs if all you want is to shorten the
list down. Just CC yourself when you are not quite sure you assigned a bug
report properly or when you requested information. You can always un-CC when
you find the bug has landed in the right hands.
Bug-wrangling is an exhausting job. Don't try to do everything. This
means that you better keep check on the bug reports you responded to and help
guide them to satisfactory solutions.
How to contact us
Please refer to the developer list above.
You can find some of us on the Freenode network in #gentoo-bugs.
Page updated May 30, 2012
Summary: The Gentoo Bug Wranglers project controls, describes the tasks to be carried out and goals to be achieved for everyone who wrangles bugs on Gentoo's bug tracker.
Donate to support our development efforts.