Bug Wranglers

Bug Wranglers
Description	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.
Project email	bug-wranglers@gentoo.org
IRC channel	#gentoo-bugs
Lead(s)	Jeroen Roovers (jer) Developer No lead election date set
Member(s)	Jonas Stein (jstein) Developer Lars Wendler (Polynomial-C) Developer
Subproject(s) (and inherited member(s))	(none)
Parent Project	Quality Assurance
Project listing

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

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.

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 project teams, maintainers, the role of metadata.xml, who are bug wranglers and how one should contact them.

Recruitment

We are currently looking for users interested in helping the project with one or more jobs.

To learn more, visit the Staffing Needs page.

Bug wrangling

Accessing bug reports

You can use these bugzilla queries to find a list of unassigned bug reports:

Instead of bookmarking these URLs in your web browser, you can store them in your bugzilla profile by typing a name for the search, e.g. "B-W" or "B-W-3-days" and clicking the "Remember search" button at the bottom of the result page. It's probably nice to wrangle the bug reports in order of the age of the last edit, oldest handled first. Do note that you cannot share remembered search URLs, except by loading the result page, clicking "Edit Search" and then doing some URL hackery.

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 report should stay 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 occurred.

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 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 (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 bug reports 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 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. 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 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 stabilization 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 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.
Users with editbugs privilege on Bugzilla are invited to assign their own tickets too, if possible. A JavaScript plugin for greasemonkey makes this very fast and easy.
Bugs about cross compilation should be assigned to cross@gentoo.org

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

List of Bugs which are assigned to bugwranglers

https://bugs.gentoo.org/buglist.cgi?no_redirect=1&quicksearch=assignee%3Abug-wranglers%40gentoo.org+

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.