Bug Wranglers

From Gentoo Wiki
Jump to:navigation Jump to:search
Bug Wranglers
Description Bug Wranglers elaborate how to proceed with bugs on the Gentoo bug tracker.
Project email bug-wranglers@gentoo.org
IRC channel #gentoo-bugs (webchat)
Bugs Related bugs
Last elected: 2020-05-02
(and inherited member(s))
Parent Project Quality Assurance
Project listing

The Gentoo Bug Wranglers Project elaborates how to proceed with bugs on the Gentoo bug tracker. Our goal is that bugs get fixed as efficiently as possible.

Bug wrangling

Assessing bug reports

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 report should stay assigned to bug-wranglers, and a full build log should be requested from the reporter.

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.

CODE standard format of the Summary
[name overlay] CATEGORY/PKG(-version(-revision)) - {problem description}/{action}

Bug reports about eclasses should list the full eclass filename in the Summary instead of an atom. Bug reports about profiles should list the full profile name in the Summary instead of an atom.

Acquiring more information

Bug reports can quickly get messy from comments and attachments that may or may not be appropriate to the bug being reported. 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 courteously.

  • 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. 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.
  • If `emerge --info' is missing, ask to provide it and to reopen the ticket afterwards. Mark the bug as CLOSED/NEEDINFO and wait.
  • 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.

Assigning bug reports

  • 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 security@gentoo.org immediately, using product "Gentoo Security" and component "Vulnerabilities", with the maintainers CC'd.
  • If a bug report pertains to a specific package, then you enter the package's directory in your copy of the gentoo git 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, then you assign the bug to that maintainer. When the file lists multiple entries, then you assign the bug to the first <maintainer>, and CC the other <maintainer>(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 well as you can.
  • Bug reports about packages in overlays should be assigned to the <owner> tag in repositories.xml. Some of these overlays want to get their bugs tracked elsewhere, and explicitly state this in their <description> tags.
  • 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.
  • Assign bug reports about eclasses to the eclass maintainer mentioned in the .eclass file.
  • 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 stabilization request should be handled by the package's maintainer. Others should not CC arch teams 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 qa@gentoo.org with release@gentoo.org CC'd. Exceptions are profiles that are obviously maintained by some project, like hardened, selinux, prefix, etc. Those get assigned to the maintaining project.
  • 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.
  • Bugs about cross compilation should be assigned to cross@gentoo.org
  • Bug reports that include patches or other solutions can usually be assigned directly to the maintainers.
  • If a acct-user related bug is related to a specific package, add both to the summary as in bug #729322 and assign to the package maintainer.
  • Assign bugs which occur on a specific architecture only (arm, arm64, ppc, ...) to the maintainer of the package. The maintainer of the package can ping the arch teams on IRC in order to solve the bug together.

Please contact Bug-wranglers, if we need adjustments on the above agreements.


The best approach to bug wrangling is to really get involved with individual bug reports.

  • All users with editbugs privilege on Bugzilla are invited to assign bug reports
  • Working on bug reports is an exhausting job. Don't try to do everything.
  • Some bug reports make your blood boil. Ignore them and let someone else handle them.
  • Be friendly, but not chatty.
  • Use precise wording that leads to precise answers and a solution.
  • You can CC yourself to monitor, if you assigned a bug report properly or when you requested information. You can set auto CC in your bugzilla preferences, if you like. You can always un-CC again.
  • Avoid full quotes.
  • Help to guide to satisfactory solutions.



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 labor to get all bugs properly assigned within an acceptable time frame (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 its existence.

This page is based on a document formerly found on our main website gentoo.org.
The following people contributed to the original document: jer
They are listed here because wiki history does not allow for any external attribution. If you edit the wiki article, please do not add yourself here; your contributions are recorded on each article's associated history page.