1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
|
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet href="/xsl/project.xsl" type="text/xsl"?>
<?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?>
<!DOCTYPE project SYSTEM "/dtd/project.dtd">
<project>
<name>Bug Wranglers</name>
<longname>The Bug Wranglers Project</longname>
<date>2010-05-26</date>
<author title="Author">
<mail link="jer" />
</author>
<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.
</description>
<longdescription>
<p>
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 <uri
link="http://bugs.gentoo.org/">bug tracker</uri>.</p>
<p>The project was erected after the de facto resignation of long time <e>Main
Bug Wrangler</e> Jakub Moc, when it turned out we required a division of labour
to see all bugs reassigned 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.</p>
<p>In its current phase, the project now 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.
</p>
</longdescription>
<goals>
<p>
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
<uri link="/proj/en/metastructure/herds/herds.xml">herds.xml</uri>,
who are bug wranglers and how one should contact them.
</p>
</goals>
<dev role="Lead">jer</dev>
<dev role="Member">jlec</dev>
<dev role="Member">hwoarang</dev>
<dev role="Member">Polynomial-C</dev>
<dev role="Member">wormo</dev>
<dev role="Member">ssuominen</dev>
<extrachapter>
<title>Bug Wrangling</title>
<section>
<title>Assessing Bug Reports</title>
<body>
<p>
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.
</p>
<ul>
<li>Bug reports requesting <b>version bumps</b> 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 <mail link="security@gentoo.org">security@gentoo.org</mail>
immediately, using product "Gentoo Security" and component "Vulnerabilities",
with the maintainers CC'd.</li>
<li>Bug reports that say something isn't working or compiling <b>without a
comprehensive analysis of the causes</b>, 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 <c>ASSIGNED</c> to bug-wranglers, and a full build log should
be requested from the reporter.</li>
<li>Bug reports that <b>include patches</b> or other solutions accompanying
the actual bug description can usually be assigned directly to the maintainers.</li>
<li>The <c>Summary</c> 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.</li>
<li>Bug reports that refer to a single or a few (similar) packages should
detail the <b>package atom(s)</b> as completely as possible in the
<c>Summary</c>, including a version only when other versions do not exhibit the
bug.</li>
<li>Bug reports about <b>eclasses</b> should list the full eclass filename in the
<c>Summary</c>.</li>
</ul>
</body>
</section>
<section>
<title>Acquiring More Information (and when not to)</title>
<body>
<p>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 <c>INVALID</c>, you should treat the reporter
<b>courteously</b>.</p>
<ul>
<li>If you find that a reported problem arose because <b>the reporter lacks
certain skills</b> 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 <c>TEST-REQUEST</c> (instead of as <c>INVALID</c>) and suggest that the
reporter tests the solution you provide, and that he reopens the bug only when
that doesn't solve the problem.</li>
<li>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 <b>commands that produce the information you require</b>.
Do so even if the means to that end seem trivial, like asking for `emerge
--info' or `emerge -vp cat/pkg'.</li>
<li>Do not assume that the reporter ought to know <b>how to report bugs</b>. 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 <c>ASSIGNED</c> and wait for
the information you requested.</li>
<li>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). <b>When enough information has been
presented</b> to 'make a case', it's appropriate to say so.</li>
<li>Some bugs make your blood boil. Ignore them and let someone else handle
them.</li>
</ul>
</body>
</section>
<section>
<title>Assigning Bug Reports</title>
<body>
<p>
To assign a bug report to the right people, you will need to find some more
information, depending on the type of bug report.
</p>
<ul>
<li>If a bug report pertains to a specific <b>package</b>, then you enter the
package's directory in your copy of the <uri
link="http://sources.gentoo.org/viewcvs.py/gentoo-x86/">gentoo-x86 CVS
repository</uri> (or perhaps the online version which should always be more or
less up to date) and read the <c>metadata.xml</c> file you find there. When
<c>metadata.xml</c> 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 <c>metadata.xml</c> 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 optimal as possible.</li>
<li>In cases where <c>metadata.xml</c> 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 <uri
link="/proj/en/metastructure/herds/herds.xml">herds.xml</uri> to figure out the
appropriate e-mail alias for that herd.</li>
<li>When a bug report calls attention to <b>multiple packages</b>, then things
become 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 <b>tracker
bug</b> (denoted by the <c>Tracker</c> 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.</li>
<li>Bug reports that concern <b>eclasses</b> should be assigned to the eclass
maintainer. To figure out who maintains an eclass, browse to the
<uri link="http://sources.gentoo.org/viewcvs.py/gentoo-x86/eclass">gentoo-x86/eclass</uri>
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.</li>
<li>A <b>keyword request</b> should be assigned to the package's maintainer and
CC'd to the appropriate arch team(s). The report's <c>Keywords</c> field should
contain the <c>KEYWORDREQ</c> keyword.</li>
<li>A <b>stabilisation request</b> should be handled by the package's maintainer, so
you should not CC arch teams in your role as bug wrangler, nor set the
<c>STABLEREQ</c> keyword in the <c>Keywords</c> field. Unless the package is
maintainer-needed, then you should add arches and set the Keyword field if the
bug makes sense.</li>
<li>Bug reports that concern <b>profiles</b> should be assigned to
<uri link="mailto:qa@gentoo.org">qa@gentoo.org</uri> with
<uri link="mailto:release@gentoo.org">release@gentoo.org</uri> CC'd. Exceptions
are profiles that are obviously maintained by some herd, like hardened, selinux,
prefix, etc. Those get assigned to the maintaining herd.</li>
<li>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
<c>Product</c> and <c>Component</c> fields of each bug should help you
(re)assign these reports appropriately.</li>
</ul>
</body>
</section>
</extrachapter>
<extrachapter>
<title>Participating</title>
<section>
<body>
<p>
All Gentoo developers who can change the <c>Assignee</c> 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.
</p>
<p>
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.
</p>
<p>The best approach to bug wrangling is to really <b>get involved</b> 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.</p>
<p>Bug-wrangling is an exhausting job. Don't try to do <b>everything</b>. This
means that you better keep check on the bug reports you responded to and help
guide them to satisfactory solutions.</p>
</body>
</section>
</extrachapter>
<extrachapter position="bottom">
<title>How to contact us</title>
<section>
<title>Via e-mail</title>
<body>
<p>
Please refer to the developer list above.
</p>
</body>
</section>
<section>
<title>Via IRC</title>
<body>
<p>
You can find some of us on the Freenode network in <uri link="irc://irc.freenode.net/gentoo-bugs">#gentoo-bugs</uri>.
</p>
</body>
</section>
</extrachapter>
</project>
|