| 1 |
<?xml version="1.0" encoding="utf-8"?>
|
| 2 |
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
|
| 3 |
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
|
| 4 |
<!ENTITY % commondata SYSTEM "common.ent" > %commondata;
|
| 5 |
]>
|
| 6 |
<chapter id="beyond-pkging">
|
| 7 |
<title>Beyond Packaging</title>
|
| 8 |
<para>
|
| 9 |
Debian is about a lot more than just packaging software and maintaining those
|
| 10 |
packages. This chapter contains information about ways, often really critical
|
| 11 |
ways, to contribute to Debian beyond simply creating and maintaining packages.
|
| 12 |
</para>
|
| 13 |
<para>
|
| 14 |
As a volunteer organization, Debian relies on the discretion of its members in
|
| 15 |
choosing what they want to work on and in choosing the most critical thing to
|
| 16 |
spend their time on.
|
| 17 |
</para>
|
| 18 |
<section id="submit-bug">
|
| 19 |
<title>Bug reporting</title>
|
| 20 |
<para>
|
| 21 |
We encourage you to file bugs as you find them in Debian packages. In fact,
|
| 22 |
Debian developers are often the first line testers. Finding and reporting bugs
|
| 23 |
in other developers' packages improves the quality of Debian.
|
| 24 |
</para>
|
| 25 |
<para>
|
| 26 |
Read the <ulink url="&url-bts-report;">instructions for
|
| 27 |
reporting bugs</ulink> in the Debian <ulink
|
| 28 |
url="&url-bts;">bug tracking system</ulink>.
|
| 29 |
</para>
|
| 30 |
<para>
|
| 31 |
Try to submit the bug from a normal user account at which you are likely to
|
| 32 |
receive mail, so that people can reach you if they need further information
|
| 33 |
about the bug. Do not submit bugs as root.
|
| 34 |
</para>
|
| 35 |
<para>
|
| 36 |
You can use a tool like <citerefentry> <refentrytitle>reportbug</refentrytitle>
|
| 37 |
<manvolnum>1</manvolnum> </citerefentry> to submit bugs. It can automate and
|
| 38 |
generally ease the process.
|
| 39 |
</para>
|
| 40 |
<para>
|
| 41 |
Make sure the bug is not already filed against a package. Each package has a
|
| 42 |
bug list easily reachable at
|
| 43 |
<literal>http://&bugs-host;/<replaceable>packagename</replaceable></literal>
|
| 44 |
Utilities like <citerefentry> <refentrytitle>querybts</refentrytitle>
|
| 45 |
<manvolnum>1</manvolnum> </citerefentry> can also provide you with this
|
| 46 |
information (and <command>reportbug</command> will usually invoke
|
| 47 |
<command>querybts</command> before sending, too).
|
| 48 |
</para>
|
| 49 |
<para>
|
| 50 |
Try to direct your bugs to the proper location. When for example your bug is
|
| 51 |
about a package which overwrites files from another package, check the bug
|
| 52 |
lists for <emphasis>both</emphasis> of those packages in order to avoid filing
|
| 53 |
duplicate bug reports.
|
| 54 |
</para>
|
| 55 |
<para>
|
| 56 |
For extra credit, you can go through other packages, merging bugs which are
|
| 57 |
reported more than once, or tagging bugs `fixed' when they have already been
|
| 58 |
fixed. Note that when you are neither the bug submitter nor the package
|
| 59 |
maintainer, you should not actually close the bug (unless you secure permission
|
| 60 |
from the maintainer).
|
| 61 |
</para>
|
| 62 |
<para>
|
| 63 |
From time to time you may want to check what has been going on with the bug
|
| 64 |
reports that you submitted. Take this opportunity to close those that you
|
| 65 |
can't reproduce anymore. To find out all the bugs you submitted, you just have
|
| 66 |
to visit
|
| 67 |
<literal>http://&bugs-host;/from:<replaceable><your-email-addr></replaceable></literal>.
|
| 68 |
</para>
|
| 69 |
<section id="submit-many-bugs">
|
| 70 |
<title>Reporting lots of bugs at once (mass bug filing)</title>
|
| 71 |
<para>
|
| 72 |
Reporting a great number of bugs for the same problem on a great number of
|
| 73 |
different packages — i.e., more than 10 — is a deprecated practice. Take
|
| 74 |
all possible steps to avoid submitting bulk bugs at all. For instance, if
|
| 75 |
checking for the problem can be automated, add a new check to <systemitem
|
| 76 |
role="package">lintian</systemitem> so that an error or warning is emitted.
|
| 77 |
</para>
|
| 78 |
<para>
|
| 79 |
If you report more than 10 bugs on the same topic at once, it is recommended
|
| 80 |
that you send a message to &email-debian-devel; describing
|
| 81 |
your intention before submitting the report, and mentioning the fact in the
|
| 82 |
subject of your mail. This will allow other developers to verify that the bug
|
| 83 |
is a real problem. In addition, it will help prevent a situation in which
|
| 84 |
several maintainers start filing the same bug report simultaneously.
|
| 85 |
</para>
|
| 86 |
<para>
|
| 87 |
Please use the programms <command>dd-list</command> and if appropriate
|
| 88 |
<command>whodepends</command> (from the package devscripts) to generate a list
|
| 89 |
of all affected packages, and include the output in your mail to
|
| 90 |
&email-debian-devel;.
|
| 91 |
</para>
|
| 92 |
<para>
|
| 93 |
Note that when sending lots of bugs on the same subject, you should send the
|
| 94 |
bug report to <email>maintonly@&bugs-host;</email> so that the bug report
|
| 95 |
is not forwarded to the bug distribution mailing list.
|
| 96 |
</para>
|
| 97 |
<section id="usertags">
|
| 98 |
<title>Usertags</title>
|
| 99 |
<para>
|
| 100 |
You may wish to use BTS usertags when submitting bugs across a number of
|
| 101 |
packages. Usertags are similar to normal tags such as 'patch' and 'wishlist'
|
| 102 |
but differ in that they are user-defined and occupy a namespace that is
|
| 103 |
unique to a particular user. This allows multiple sets of developers to
|
| 104 |
'usertag' the same bug in different ways without conflicting.
|
| 105 |
</para>
|
| 106 |
<para>
|
| 107 |
To add usertags when filing bugs, specify the <literal>User</literal> and
|
| 108 |
<literal>Usertags</literal> pseudo-headers:
|
| 109 |
</para>
|
| 110 |
<screen>
|
| 111 |
To: submit@bugs.debian.org
|
| 112 |
Subject: <replaceable><title-of-bug></replaceable>
|
| 113 |
|
| 114 |
Package: <replaceable><pkgname></replaceable>
|
| 115 |
<replaceable>[ ... ]</replaceable>
|
| 116 |
User: <replaceable><email-addr></replaceable>
|
| 117 |
Usertags: <replaceable><tag-name> [ <tag-name> ... ]</replaceable>
|
| 118 |
|
| 119 |
<replaceable><description-of-bug ...></replaceable>
|
| 120 |
</screen>
|
| 121 |
<para>
|
| 122 |
Note that tags are seperated by spaces and cannot contain underscores. If you
|
| 123 |
are filing bugs for for a particular group or team it is recommended that you
|
| 124 |
set the <literal>User</literal> to an appropriate mailing list after describing
|
| 125 |
your intention there.
|
| 126 |
</para>
|
| 127 |
<para>
|
| 128 |
To view bugs tagged with a specific usertag, visit
|
| 129 |
<literal>http://&bugs-host;/cgi-bin/pkgreport.cgi?users=<replaceable><email-addr></replaceable>&tag=<replaceable><tag-name></replaceable></literal>.
|
| 130 |
</para>
|
| 131 |
</section>
|
| 132 |
</section>
|
| 133 |
|
| 134 |
</section>
|
| 135 |
|
| 136 |
<section id="qa-effort">
|
| 137 |
<title>Quality Assurance effort</title>
|
| 138 |
<section id="qa-daily-work">
|
| 139 |
<title>Daily work</title>
|
| 140 |
<para>
|
| 141 |
Even though there is a dedicated group of people for Quality Assurance, QA
|
| 142 |
duties are not reserved solely for them. You can participate in this effort by
|
| 143 |
keeping your packages as bug-free as possible, and as lintian-clean (see <xref
|
| 144 |
linkend="lintian"/> ) as possible. If you do not find that possible, then you
|
| 145 |
should consider orphaning some of your packages (see <xref
|
| 146 |
linkend="orphaning"/> ). Alternatively, you may ask the help of other people
|
| 147 |
in order to catch up with the backlog of bugs that you have (you can ask for
|
| 148 |
help on &email-debian-qa; or
|
| 149 |
&email-debian-devel;). At the same time, you can look for
|
| 150 |
co-maintainers (see <xref linkend="collaborative-maint"/> ).
|
| 151 |
</para>
|
| 152 |
</section>
|
| 153 |
|
| 154 |
<section id="qa-bsp">
|
| 155 |
<title>Bug squashing parties</title>
|
| 156 |
<para>
|
| 157 |
From time to time the QA group organizes bug squashing parties to get rid of as
|
| 158 |
many problems as possible. They are announced on
|
| 159 |
&email-debian-devel-announce; and the announcement explains
|
| 160 |
which area will be the focus of the party: usually they focus on release
|
| 161 |
critical bugs but it may happen that they decide to help finish a major upgrade
|
| 162 |
(like a new <command>perl</command> version which requires recompilation of all
|
| 163 |
the binary modules).
|
| 164 |
</para>
|
| 165 |
<para>
|
| 166 |
The rules for non-maintainer uploads differ during the parties because the
|
| 167 |
announcement of the party is considered prior notice for NMU. If you have
|
| 168 |
packages that may be affected by the party (because they have release critical
|
| 169 |
bugs for example), you should send an update to each of the corresponding bug
|
| 170 |
to explain their current status and what you expect from the party. If you
|
| 171 |
don't want an NMU, or if you're only interested in a patch, or if you will deal
|
| 172 |
yourself with the bug, please explain that in the BTS.
|
| 173 |
</para>
|
| 174 |
<para>
|
| 175 |
People participating in the party have special rules for NMU, they can NMU
|
| 176 |
without prior notice if they upload their NMU to DELAYED/3-day at least. All
|
| 177 |
other NMU rules apply as usually; they should send the patch of the NMU to the
|
| 178 |
BTS (to one of the open bugs fixed by the NMU, or to a new bug, tagged fixed).
|
| 179 |
They should also respect any particular wishes of the maintainer.
|
| 180 |
</para>
|
| 181 |
<para>
|
| 182 |
If you don't feel confident about doing an NMU, just send a patch to the BTS.
|
| 183 |
It's far better than a broken NMU.
|
| 184 |
</para>
|
| 185 |
</section>
|
| 186 |
|
| 187 |
</section>
|
| 188 |
|
| 189 |
<section id="contacting-maintainers">
|
| 190 |
<title>Contacting other maintainers</title>
|
| 191 |
<para>
|
| 192 |
During your lifetime within Debian, you will have to contact other maintainers
|
| 193 |
for various reasons. You may want to discuss a new way of cooperating between
|
| 194 |
a set of related packages, or you may simply remind someone that a new upstream
|
| 195 |
version is available and that you need it.
|
| 196 |
</para>
|
| 197 |
<para>
|
| 198 |
Looking up the email address of the maintainer for the package can be
|
| 199 |
distracting. Fortunately, there is a simple email alias,
|
| 200 |
<literal><package>@&packages-host;</literal>, which provides a way to
|
| 201 |
email the maintainer, whatever their individual email address (or addresses)
|
| 202 |
may be. Replace <literal><package></literal> with the name of a source
|
| 203 |
or a binary package.
|
| 204 |
</para>
|
| 205 |
<para>
|
| 206 |
You may also be interested in contacting the persons who are subscribed to a
|
| 207 |
given source package via <xref linkend="pkg-tracking-system"/> . You can do so
|
| 208 |
by using the <literal><package>@&pts-host;</literal> email
|
| 209 |
address.
|
| 210 |
</para>
|
| 211 |
<!-- FIXME: moo@packages.d.o is easily confused with moo@packages.qa.d.o -->
|
| 212 |
</section>
|
| 213 |
|
| 214 |
<section id="mia-qa">
|
| 215 |
<title>Dealing with inactive and/or unreachable maintainers</title>
|
| 216 |
<para>
|
| 217 |
If you notice that a package is lacking maintenance, you should make sure that
|
| 218 |
the maintainer is active and will continue to work on their packages. It is
|
| 219 |
possible that they are not active any more, but haven't registered out of the
|
| 220 |
system, so to speak. On the other hand, it is also possible that they just
|
| 221 |
need a reminder.
|
| 222 |
</para>
|
| 223 |
<para>
|
| 224 |
There is a simple system (the MIA database) in which information about
|
| 225 |
maintainers who are deemed Missing In Action is recorded. When a member of the
|
| 226 |
QA group contacts an inactive maintainer or finds more information about one,
|
| 227 |
this is recorded in the MIA database. This system is available in
|
| 228 |
<filename>/org/qa.debian.org/mia</filename> on the host <literal>qa.debian.org
|
| 229 |
</literal>, and can be queried with the <command>mia-query</command> tool.
|
| 230 |
Use <command>mia-query --help</command> to see how to query the database.
|
| 231 |
If you find that no information has been recorded about an inactive maintainer yet,
|
| 232 |
or that you can add more information, you should generally proceed as follows.
|
| 233 |
</para>
|
| 234 |
<para>
|
| 235 |
The first step is to politely contact the maintainer, and wait a reasonable
|
| 236 |
time for a response. It is quite hard to define reasonable time, but it is
|
| 237 |
important to take into account that real life is sometimes very hectic. One
|
| 238 |
way to handle this would be to send a reminder after two weeks.
|
| 239 |
</para>
|
| 240 |
<para>
|
| 241 |
If the maintainer doesn't reply within four weeks (a month), one can assume
|
| 242 |
that a response will probably not happen. If that happens, you should
|
| 243 |
investigate further, and try to gather as much useful information about the
|
| 244 |
maintainer in question as possible. This includes:
|
| 245 |
</para>
|
| 246 |
<itemizedlist>
|
| 247 |
<listitem>
|
| 248 |
<para>
|
| 249 |
The <literal>echelon</literal> information available through the <ulink
|
| 250 |
url="&url-debian-db;">developers' LDAP database</ulink>, which indicates
|
| 251 |
when the developer last posted to a Debian mailing list. (This includes
|
| 252 |
mails about uploads distributed via the &email-debian-devel-changes; list.)
|
| 253 |
Also, remember to check whether the maintainer is marked as on vacation in
|
| 254 |
the database.
|
| 255 |
</para>
|
| 256 |
</listitem>
|
| 257 |
<listitem>
|
| 258 |
<para>
|
| 259 |
The number of packages this maintainer is responsible for, and the condition of
|
| 260 |
those packages. In particular, are there any RC bugs that have been open for
|
| 261 |
ages? Furthermore, how many bugs are there in general? Another important
|
| 262 |
piece of information is whether the packages have been NMUed, and if so, by
|
| 263 |
whom.
|
| 264 |
</para>
|
| 265 |
</listitem>
|
| 266 |
<listitem>
|
| 267 |
<para>
|
| 268 |
Is there any activity of the maintainer outside of Debian? For example, they
|
| 269 |
might have posted something recently to non-Debian mailing lists or news
|
| 270 |
groups.
|
| 271 |
</para>
|
| 272 |
</listitem>
|
| 273 |
</itemizedlist>
|
| 274 |
<para>
|
| 275 |
A bit of a problem are packages which were sponsored — the maintainer is not
|
| 276 |
an official Debian developer. The <literal>echelon</literal> information is not
|
| 277 |
available for sponsored people, for example, so you need to find and contact the
|
| 278 |
Debian developer who has actually uploaded the package. Given that they signed
|
| 279 |
the package, they're responsible for the upload anyhow, and are likely to know
|
| 280 |
what happened to the person they sponsored.
|
| 281 |
</para>
|
| 282 |
<para>
|
| 283 |
It is also allowed to post a query to &email-debian-devel;,
|
| 284 |
asking if anyone is aware of the whereabouts of the missing maintainer. Please
|
| 285 |
Cc: the person in question.
|
| 286 |
</para>
|
| 287 |
<para>
|
| 288 |
Once you have gathered all of this, you can contact
|
| 289 |
&email-mia;. People on this alias will use the
|
| 290 |
information you provide in order to decide how to proceed. For example, they
|
| 291 |
might orphan one or all of the packages of the maintainer. If a package has
|
| 292 |
been NMUed, they might prefer to contact the NMUer before orphaning the package
|
| 293 |
— perhaps the person who has done the NMU is interested in the package.
|
| 294 |
</para>
|
| 295 |
<para>
|
| 296 |
One last word: please remember to be polite. We are all volunteers and cannot
|
| 297 |
dedicate all of our time to Debian. Also, you are not aware of the
|
| 298 |
circumstances of the person who is involved. Perhaps they might be seriously
|
| 299 |
ill or might even have died — you do not know who may be on the receiving
|
| 300 |
side. Imagine how a relative will feel if they read the e-mail of the deceased
|
| 301 |
and find a very impolite, angry and accusing message!
|
| 302 |
</para>
|
| 303 |
<para>
|
| 304 |
On the other hand, although we are volunteers, we do have a responsibility. So
|
| 305 |
you can stress the importance of the greater good — if a maintainer does not
|
| 306 |
have the time or interest anymore, they should let go and give the package to
|
| 307 |
someone with more time.
|
| 308 |
</para>
|
| 309 |
<para>
|
| 310 |
If you are interested in working in the MIA team, please have a look at the
|
| 311 |
README file in <filename>/org/qa.debian.org/mia</filename> on <literal>
|
| 312 |
qa.debian.org</literal> where the technical details and the MIA procedures are
|
| 313 |
documented and contact &email-mia;.
|
| 314 |
</para>
|
| 315 |
</section>
|
| 316 |
|
| 317 |
<section id="newmaint">
|
| 318 |
<title>Interacting with prospective Debian developers</title>
|
| 319 |
<para>
|
| 320 |
Debian's success depends on its ability to attract and retain new and talented
|
| 321 |
volunteers. If you are an experienced developer, we recommend that you get
|
| 322 |
involved with the process of bringing in new developers. This section
|
| 323 |
describes how to help new prospective developers.
|
| 324 |
</para>
|
| 325 |
<section id="sponsoring">
|
| 326 |
<title>Sponsoring packages</title>
|
| 327 |
<para>
|
| 328 |
Sponsoring a package means uploading a package for a maintainer who is not able
|
| 329 |
to do it on their own, a new maintainer applicant. Sponsoring a package also
|
| 330 |
means accepting responsibility for it.
|
| 331 |
</para>
|
| 332 |
<!-- FIXME: service down
|
| 333 |
<para>
|
| 334 |
If you wish to volunteer as a sponsor, you can sign up at <ulink
|
| 335 |
url="http://www.internatif.org/bortzmeyer/debian/sponsor/">http://www.internatif.org/bortzmeyer/debian/sponsor/</ulink>.
|
| 336 |
</para>
|
| 337 |
-->
|
| 338 |
<para>
|
| 339 |
New maintainers usually have certain difficulties creating Debian packages —
|
| 340 |
this is quite understandable. That is why the sponsor is there, to check the
|
| 341 |
package and verify that it is good enough for inclusion in Debian. (Note that
|
| 342 |
if the sponsored package is new, the ftpmasters will also have to inspect it
|
| 343 |
before letting it in.)
|
| 344 |
</para>
|
| 345 |
<para>
|
| 346 |
Sponsoring merely by signing the upload or just recompiling is <emphasis
|
| 347 |
role="strong">definitely not recommended</emphasis>. You need to build the
|
| 348 |
source package just like you would build a package of your own. Remember that
|
| 349 |
it doesn't matter that you left the prospective developer's name both in the
|
| 350 |
changelog and the control file, the upload can still be traced to you.
|
| 351 |
</para>
|
| 352 |
<para>
|
| 353 |
If you are an application manager for a prospective developer, you can also be
|
| 354 |
their sponsor. That way you can also verify how the applicant is handling the
|
| 355 |
'Tasks and Skills' part of their application.
|
| 356 |
</para>
|
| 357 |
</section>
|
| 358 |
|
| 359 |
<section id="s7.5.2">
|
| 360 |
<title>Managing sponsored packages</title>
|
| 361 |
<para>
|
| 362 |
By uploading a sponsored package to Debian, you are certifying that the package
|
| 363 |
meets minimum Debian standards. That implies that you must build and test the
|
| 364 |
package on your own system before uploading.
|
| 365 |
</para>
|
| 366 |
<para>
|
| 367 |
You cannot simply upload a binary <filename>.deb</filename> from the sponsoree.
|
| 368 |
In theory, you should only ask for the diff file and the location of the
|
| 369 |
original source tarball, and then you should download the source and apply the
|
| 370 |
diff yourself. In practice, you may want to use the source package built by
|
| 371 |
your sponsoree. In that case, you have to check that they haven't altered the
|
| 372 |
upstream files in the <filename>.orig.tar.gz</filename> file that they're
|
| 373 |
providing.
|
| 374 |
</para>
|
| 375 |
<para>
|
| 376 |
Do not be afraid to write the sponsoree back and point out changes that need to
|
| 377 |
be made. It often takes several rounds of back-and-forth email before the
|
| 378 |
package is in acceptable shape. Being a sponsor means being a mentor.
|
| 379 |
</para>
|
| 380 |
<para>
|
| 381 |
Once the package meets Debian standards, build and sign it with
|
| 382 |
</para>
|
| 383 |
<screen>
|
| 384 |
dpkg-buildpackage -k<replaceable>KEY-ID</replaceable>
|
| 385 |
</screen>
|
| 386 |
<para>
|
| 387 |
before uploading it to the incoming directory. Of course, you can also use any
|
| 388 |
part of your <replaceable>KEY-ID</replaceable>, as long as it's unique in your
|
| 389 |
secret keyring.
|
| 390 |
</para>
|
| 391 |
<para>
|
| 392 |
The Maintainer field of the <filename>control</filename> file and the
|
| 393 |
<filename>changelog</filename> should list the person who did the packaging,
|
| 394 |
i.e., the sponsoree. The sponsoree will therefore get all the BTS mail about
|
| 395 |
the package.
|
| 396 |
</para>
|
| 397 |
<para>
|
| 398 |
If you prefer to leave a more evident trace of your sponsorship job, you can
|
| 399 |
add a line stating it in the most recent changelog entry.
|
| 400 |
</para>
|
| 401 |
<para>
|
| 402 |
You are encouraged to keep tabs on the package you sponsor using <xref
|
| 403 |
linkend="pkg-tracking-system"/> .
|
| 404 |
</para>
|
| 405 |
</section>
|
| 406 |
|
| 407 |
<section id="s7.5.3">
|
| 408 |
<title>Advocating new developers</title>
|
| 409 |
<para>
|
| 410 |
See the page about <ulink
|
| 411 |
url="&url-newmaint-advocate;">advocating a prospective
|
| 412 |
developer</ulink> at the Debian web site.
|
| 413 |
</para>
|
| 414 |
</section>
|
| 415 |
|
| 416 |
<section id="s7.5.4">
|
| 417 |
<title>Handling new maintainer applications</title>
|
| 418 |
<para>
|
| 419 |
Please see <ulink url="&url-newmaint-amchecklist;">Checklist
|
| 420 |
for Application Managers</ulink> at the Debian web site.
|
| 421 |
</para>
|
| 422 |
</section>
|
| 423 |
|
| 424 |
</section>
|
| 425 |
|
| 426 |
</chapter>
|
| 427 |
|
Parent Directory
| 
Revision Log