Project:Bug-wranglers

The Gentoo Bug Wranglers Project elaborates how to proceed with bugs on the Gentoo bug tracker.

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

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

Bug reports about eclasses should list the full eclass filename in the  instead of an atom. Bug reports about profiles should list the full profile name in the  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, 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  (instead of as   ) 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 or.
 * If `emerge --info' is missing, ask to provide it and to reopen the ticket afterwards. Mark the bug as  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 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
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 file you find there. When  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 , and CC the other  (s). If you find that  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  tag in . Some of these overlays want to get their bugs tracked elsewhere, and explicitly state this in their   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  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.
 * 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  field should contain the   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  keyword in the   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 [mailto:qa@gentoo.org qa@gentoo.org] with [mailto:release@gentoo.org 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  and   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  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.
 * Bug-wrangling 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.

Ressources

 * Bug Template for the Wiki pages
 * New unassigned bug tickets which are still assigned to Bugwranglers (also available in your bugzilla Preferences -> Saved Searches)

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