The Bug Wranglers Project

1.  Project Description

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 its existence.

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 page.

2.  Project Goals

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 herds.xml, who are bug wranglers and how one should contact them.

3.  Developers

All developers can be reached by e-mail using nickname@gentoo.org.

4.  Recruitment

We are currently looking for users interested in helping the project with the following jobs:

Bug Wrangler

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, etc.)

Requirements

Good understanding of Gentoo and Bugzilla, always respecting the users.

Contact

Jeroen Roovers

5.  Bug Wrangling

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 security@gentoo.org 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)) in the Summary, including 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.
• Bug reports about eclasses should list the full eclass filename in the Summary.

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 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, 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 them.

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 possible.
• 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 clear.
• Bug reports that concern eclasses should be assigned to the eclass maintainer. To figure out who maintains an eclass, browse to the gentoo-x86/eclass 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 report's assignee.
• 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 qa@gentoo.org with release@gentoo.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.

6.  Participating

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 where possible.

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.

7.  How to contact us

Via e-mail

Please refer to the developer list above.

Via IRC

You can find some of us on the Freenode network in #gentoo-bugs.