reports that you submitted. Take this opportunity to close those that you
can't reproduce anymore. To find out all the bugs you submitted, you just have
to visit
-<literal>http://&bugs-host;/from:<replaceable><your-email-addr></replaceable></literal>.
+<literal>http://&bugs-host;/from:<replaceable>your-email-addr</replaceable></literal>.
</para>
<section id="submit-many-bugs">
<title>Reporting lots of bugs at once (mass bug filing)</title>
several maintainers start filing the same bug report simultaneously.
</para>
<para>
-Please use the programms <command>dd-list</command> and if appropriate
-<command>whodepends</command> (from the package devscripts) to generate a list
+Please use the programs <command>dd-list</command> and if appropriate
+<command>whodepends</command> (from the package <systemitem role="package">devscripts</systemitem>) to generate a list
of all affected packages, and include the output in your mail to
&email-debian-devel;.
</para>
bug report to <email>maintonly@&bugs-host;</email> so that the bug report
is not forwarded to the bug distribution mailing list.
</para>
+<section id="usertags">
+<title>Usertags</title>
+<para>
+You may wish to use BTS usertags when submitting bugs across a number of
+packages. Usertags are similar to normal tags such as 'patch' and 'wishlist'
+but differ in that they are user-defined and occupy a namespace that is
+unique to a particular user. This allows multiple sets of developers to
+'usertag' the same bug in different ways without conflicting.
+</para>
+<para>
+To add usertags when filing bugs, specify the <literal>User</literal> and
+<literal>Usertags</literal> pseudo-headers:
+</para>
+<screen>
+To: submit@bugs.debian.org
+Subject: <replaceable>title-of-bug</replaceable>
+
+Package: <replaceable>pkgname</replaceable>
+<replaceable>[ ... ]</replaceable>
+User: <replaceable>email-addr</replaceable>
+Usertags: <replaceable>tag-name [ tag-name ... ]</replaceable>
+
+<replaceable>description-of-bug ...</replaceable>
+</screen>
+<para>
+Note that tags are seperated by spaces and cannot contain underscores. If you
+are filing bugs for a particular group or team it is recommended that you
+set the <literal>User</literal> to an appropriate mailing list after describing
+your intention there.
+</para>
+<para>
+To view bugs tagged with a specific usertag, visit
+<literal>http://&bugs-host;/cgi-bin/pkgreport.cgi?users=<replaceable>email-addr</replaceable>&tag=<replaceable>tag-name</replaceable></literal>.
+</para>
+</section>
</section>
</section>
Even though there is a dedicated group of people for Quality Assurance, QA
duties are not reserved solely for them. You can participate in this effort by
keeping your packages as bug-free as possible, and as lintian-clean (see <xref
-linkend="lintian"/> ) as possible. If you do not find that possible, then you
+linkend="lintian"/>) as possible. If you do not find that possible, then you
should consider orphaning some of your packages (see <xref
-linkend="orphaning"/> ). Alternatively, you may ask the help of other people
+linkend="orphaning"/>). Alternatively, you may ask the help of other people
in order to catch up with the backlog of bugs that you have (you can ask for
help on &email-debian-qa; or
&email-debian-devel;). At the same time, you can look for
-co-maintainers (see <xref linkend="collaborative-maint"/> ).
+co-maintainers (see <xref linkend="collaborative-maint"/>).
</para>
</section>
&email-debian-devel-announce; and the announcement explains
which area will be the focus of the party: usually they focus on release
critical bugs but it may happen that they decide to help finish a major upgrade
-(like a new perl version which requires recompilation of all the binary
-modules).
+(like a new <command>perl</command> version which requires recompilation of all
+the binary modules).
</para>
<para>
The rules for non-maintainer uploads differ during the parties because the
<para>
Looking up the email address of the maintainer for the package can be
distracting. Fortunately, there is a simple email alias,
-<literal><package>@&packages-host;</literal>, which provides a way to
+<literal><replaceable>package</replaceable>@&packages-host;</literal>, which provides a way to
email the maintainer, whatever their individual email address (or addresses)
-may be. Replace <literal><package></literal> with the name of a source
+may be. Replace <replaceable>package</replaceable> with the name of a source
or a binary package.
</para>
<para>
You may also be interested in contacting the persons who are subscribed to a
-given source package via <xref linkend="pkg-tracking-system"/> . You can do so
-by using the <literal><package>@&pts-host;</literal> email
+given source package via <xref linkend="pkg-tracking-system"/>. You can do so
+by using the <literal><replaceable>package</replaceable>@&pts-host;</literal> email
address.
</para>
<!-- FIXME: moo@packages.d.o is easily confused with moo@packages.qa.d.o -->
maintainers who are deemed Missing In Action is recorded. When a member of the
QA group contacts an inactive maintainer or finds more information about one,
this is recorded in the MIA database. This system is available in
-/org/qa.debian.org/mia on the host qa.debian.org, and can be queried with a
-tool known as <command>mia-query</command>. Use <command>mia-query --help</command>
-to see how to query the database. If you find that no information has been
-recorded about an inactive maintainer yet, or that you can add more
-information, you should generally proceed as follows.
+<filename>/org/qa.debian.org/mia</filename> on the host <literal>qa.debian.org</literal>,
+and can be queried with the <command>mia-query</command> tool.
+Use <command>mia-query --help</command> to see how to query the database.
+If you find that no information has been recorded about an inactive maintainer yet,
+or that you can add more information, you should generally proceed as follows.
</para>
<para>
The first step is to politely contact the maintainer, and wait a reasonable
<itemizedlist>
<listitem>
<para>
-The echelon information available through the <ulink
+The <literal>echelon</literal> information available through the <ulink
url="&url-debian-db;">developers' LDAP database</ulink>, which indicates
when the developer last posted to a Debian mailing list. (This includes
-uploads via debian-*-changes lists.) Also, remember to check whether the
-maintainer is marked as on vacation in the database.
+mails about uploads distributed via the &email-debian-devel-changes; list.)
+Also, remember to check whether the maintainer is marked as on vacation in
+the database.
</para>
</listitem>
<listitem>
</itemizedlist>
<para>
A bit of a problem are packages which were sponsored — the maintainer is not
-an official Debian developer. The echelon information is not available for
-sponsored people, for example, so you need to find and contact the Debian
-developer who has actually uploaded the package. Given that they signed the
-package, they're responsible for the upload anyhow, and are likely to know what
-happened to the person they sponsored.
+an official Debian developer. The <literal>echelon</literal> information is not
+available for sponsored people, for example, so you need to find and contact the
+Debian developer who has actually uploaded the package. Given that they signed
+the package, they're responsible for the upload anyhow, and are likely to know
+what happened to the person they sponsored.
</para>
<para>
It is also allowed to post a query to &email-debian-devel;,
</para>
<para>
If you are interested in working in the MIA team, please have a look at the
-README file in /org/qa.debian.org/mia on qa.debian.org where the technical
-details and the MIA procedures are documented and contact
-&email-mia;.
+<filename>README</filename> file in <filename>/org/qa.debian.org/mia</filename> on
+<literal>qa.debian.org</literal> where the technical details and the MIA procedures are
+documented and contact &email-mia;.
</para>
</section>
<title>Sponsoring packages</title>
<para>
Sponsoring a package means uploading a package for a maintainer who is not able
-to do it on their own, a new maintainer applicant. Sponsoring a package also
-means accepting responsibility for it.
+to do it on their own. It's not a trivial matter, the sponsor must verify
+the packaging and ensure that it is of the high level of quality that
+Debian strives to have.
</para>
-<!-- FIXME: service down
<para>
-If you wish to volunteer as a sponsor, you can sign up at <ulink
-url="http://www.internatif.org/bortzmeyer/debian/sponsor/">http://www.internatif.org/bortzmeyer/debian/sponsor/</ulink>.
+Debian Developers can sponsor packages. Debian Maintainers can't.
</para>
--->
<para>
-New maintainers usually have certain difficulties creating Debian packages —
-this is quite understandable. That is why the sponsor is there, to check the
-package and verify that it is good enough for inclusion in Debian. (Note that
-if the sponsored package is new, the ftpmasters will also have to inspect it
-before letting it in.)
+The process of sponsoring a package is:
+<orderedlist numeration="arabic">
+<listitem>
+<para>The maintainer prepares a source package (<filename>.dsc</filename>) and puts it online
+somewhere (like on <ulink url="http://mentors.debian.net/cgi-bin/welcome">mentors.debian.net</ulink>) or even better, provides
+a link to a public VCS repository (see <xref linkend="servers-vcs"/>) where
+the package is maintained.</para>
+</listitem>
+<listitem>
+<para>The sponsor downloads (or checkouts) the source package.</para>
+</listitem>
+<listitem>
+<para>The sponsor reviews the source package. If she finds issues, she
+informs the maintainer and asks her to provide a fixed version (the
+process starts over at step 1).</para>
+</listitem>
+<listitem>
+<para>The sponsor could not find any remaining problem. She builds the
+package, signs it, and uploads it to Debian.</para>
+</listitem>
+</orderedlist>
</para>
<para>
-Sponsoring merely by signing the upload or just recompiling is <emphasis
-role="strong">definitely not recommended</emphasis>. You need to build the
-source package just like you would build a package of your own. Remember that
-it doesn't matter that you left the prospective developer's name both in the
-changelog and the control file, the upload can still be traced to you.
+Before delving in the details of how to sponsor a package, you should
+ask yourself whether adding the proposed package is beneficial to Debian.
</para>
<para>
-If you are an application manager for a prospective developer, you can also be
-their sponsor. That way you can also verify how the applicant is handling the
-'Tasks and Skills' part of their application.
+There's no simple rule to answer this question, it can depend on many
+factors: is the upstream codebase mature and not full of security holes?
+Are there pre-existing packages that can do the same task and how do they
+compare to this new package? Has the new package been requested by users
+and how large is the user base? How active are the upstream developers?
+</para>
+<para>
+You should also ensure that the prospective maintainer is going
+to be a good maintainer. Does she already have some experience with other
+packages? If yes, is she doing a good job with them (check out some bugs)?
+Is she familiar with the package and its programming language?
+Does she have the skills needed for this package? If not, is she able
+to learn them?
</para>
-</section>
-
-<section id="s7.5.2">
-<title>Managing sponsored packages</title>
<para>
-By uploading a sponsored package to Debian, you are certifying that the package
-meets minimum Debian standards. That implies that you must build and test the
-package on your own system before uploading.
+It's also a good idea to know where she stands towards Debian: does
+she agree with Debian's philosophy and does she intend to join Debian?
+Given how easy it is to become a Debian Maintainer, you might want
+to only sponsor people who plan to join. That way you know from the start
+that you won't have to act as a sponsor indefinitely.
</para>
+<section id="sponsoring-new-package">
+<title>Sponsoring a new package</title>
<para>
-You cannot simply upload a binary <filename>.deb</filename> from the sponsoree.
-In theory, you should only ask for the diff file and the location of the
-original source tarball, and then you should download the source and apply the
-diff yourself. In practice, you may want to use the source package built by
-your sponsoree. In that case, you have to check that they haven't altered the
-upstream files in the <filename>.orig.tar.gz</filename> file that they're
-providing.
+New maintainers usually have certain difficulties creating Debian packages —
+this is quite understandable. They will do mistakes. That's why sponsoring
+a brand new package into Debian requires a thorough review of the Debian
+packaging. Sometimes several iterations will be needed until the package
+is good enough to be uploaded to Debian. Thus being a sponsor implies being
+a mentor.
</para>
<para>
-Do not be afraid to write the sponsoree back and point out changes that need to
-be made. It often takes several rounds of back-and-forth email before the
-package is in acceptable shape. Being a sponsor means being a mentor.
+Don't ever sponsor a new package without reviewing it. The review
+of new packages done by ftpmasters mainly ensures that the software
+is really free. Of course, it happens that they stumble on packaging
+problems but they really should not. It's your task to ensure that
+the uploaded package complies with the Debian Free Software Guidelines and
+is of good quality.
</para>
<para>
-Once the package meets Debian standards, build and sign it with
+Building the package and testing the software is part of the review, but
+it's also not enough. The rest of this section contains a non-exhaustive
+list of points to check in your review.
+<footnote>
+<para>
+You can find more checks in the wiki where several developers share their own
+<ulink url="http://wiki.debian.org/SponsorChecklist">sponsorship checklists</ulink>.
+</para>
+</footnote>
</para>
+<itemizedlist>
+<listitem>
+<para>Verify that the upstream tarball provided is the same that has been
+distributed by the upstream author (when the sources are repackaged for
+Debian, generate the modified tarball yourself).</para>
+</listitem>
+<listitem>
+<para>Run <command>lintian</command> (see <xref linkend="lintian"/>). It will catch many common
+problems. Be sure to verify that any <command>lintian</command> overrides setup by the
+maintainer is fully justified.</para>
+</listitem>
+<listitem>
+<para>Run <command>licensecheck</command> (part of <xref linkend="devscripts"/>) and verify that
+<filename>debian/copyright</filename> seems correct and complete. Look for
+license problems (like files with “All rights reserved”
+headers, or with a non-DFSG compliant license). <command>grep -ri</command>
+is your friend for this task.</para>
+</listitem>
+<listitem>
+<para>Build the package with <command>pbuilder</command> (or any similar tool, see <xref
+linkend="pbuilder"/>) to ensure that the build-dependencies are
+complete.</para>
+</listitem>
+<listitem>
+<para>Proofread <filename>debian/control</filename>: does it follow the
+best practices (see <xref linkend="bpp-debian-control"/>)? Are the dependencies
+complete?</para>
+</listitem>
+<listitem>
+<para>Proofread <filename>debian/rules</filename>: does it follow the
+best practices (see <xref linkend="bpp-debian-rules"/>)? Do you see some
+possible improvements?</para>
+</listitem>
+<listitem>
+<para>Proofread the maintainer scripts (<filename>preinst</filename>,
+<filename>postinst</filename>, <filename>prerm</filename>,
+<filename>postrm</filename>, <filename>config</filename>): will the
+<filename>preinst</filename>/<filename>postrm</filename> work when the dependencies are not
+installed? Are all the scripts idempotent (i.e. can you run them multiple
+times without consequences)?</para>
+</listitem>
+<listitem>
+<para>Review any change to upstream files (either in <filename>.diff.gz</filename>, or in
+<filename>debian/patches/</filename> or directly embedded in the <filename>debian</filename>
+tarball for binary files). Are they justified? Are they properly
+documented (with <ulink url="&url-dep3;">DEP-3</ulink> for patches)?</para>
+</listitem>
+<listitem>
+<para>For every file, ask yourself why the file is there and whether it's
+the right way to achieve the desired result. Is the maintainer following
+the best packaging practices (see <xref
+linkend="best-pkging-practices"/>)?</para>
+</listitem>
+<listitem>
+<para>Build the packages, install them and try the software. Ensure you can
+remove and purge the packages. Maybe test them with <command>piuparts</command>.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+If the audit did not reveal any problem, you can build the package and
+upload it to Debian. Remember that even if you're not the maintainer,
+the sponsor is still responsible of what he uploaded to Debian. That's
+why you're encouraged to keep up with the package through the
+<xref linkend="pkg-tracking-system"/>.
+</para>
+<para>
+Note that you should not need to modify the source package to put your name
+in the <filename>changelog</filename> or in the <filename>control</filename> file. The <literal>Maintainer</literal>
+field of the <filename>control</filename> file and the
+<filename>changelog</filename> should list the person who did the
+packaging, i.e. the sponsoree. That way she will get all the BTS mail.
+</para>
+<para>Instead you should instruct <command>dpkg-buildpackage</command> to use your key for
+the signature. You do that with the <literal>-k</literal> option:</para>
<screen>
dpkg-buildpackage -k<replaceable>KEY-ID</replaceable>
</screen>
+<para>If you use <command>debuild</command> and <command>debsign</command>, you can even configure it permanently
+in <filename>~/.devscripts</filename>:</para>
+<programlisting>
+DEBSIGN_KEYID=<replaceable>KEY-ID</replaceable>
+</programlisting>
+</section>
+
+<section id="sponsoring-update">
+<title>Sponsoring an update of an existing package</title>
+<para>
+You will usually assume that the package has already gone through a full
+review. So instead of doing it again, you will carefully analyze the
+difference between the current version and the new version prepared by the
+maintainer. If you have not done the initial review yourself, you might
+still want to have a more deeper look just in case the initial reviewer
+was sloppy.
+</para>
+<para>
+To be able to analyze the difference you need both versions. Download the
+current version of the source package (with <command>apt-get source</command>)
+and rebuild it (or download the current binary packages with
+<command>aptitude download</command>). Download the source package to sponsor
+(usually with <command>dget</command>).
+</para>
+<para>
+Read the new changelog entry, it should tell you what to expect during the
+review. The main tool you will use is <command>debdiff</command> (provide by
+the <systemitem role="package">devscripts</systemitem> package), you can run it with two source packages (<filename>.dsc</filename>
+files), or two binary packages, or two <filename>.changes</filename> files (it will then
+compare all the binary packages listed in the <filename>.changes</filename>).
+</para>
<para>
-before uploading it to the incoming directory. Of course, you can also use any
-part of your <replaceable>KEY-ID</replaceable>, as long as it's unique in your
-secret keyring.
+If you compare the source packages (excluding upstream files in the case
+of a new upstream version, for example by filtering the output of <command>debdiff</command>
+with <command>filterdiff -i '*/debian/*'</command>), you must understand all the
+changes you see and they should be properly documented in the Debian
+changelog.
</para>
<para>
-The Maintainer field of the <filename>control</filename> file and the
-<filename>changelog</filename> should list the person who did the packaging,
-i.e., the sponsoree. The sponsoree will therefore get all the BTS mail about
-the package.
+If everything is fine, build the package and compare the binary packages
+to verify that the changes on the source package have no unexpected
+consequences (like some files dropped by mistake, missing dependencies,
+etc.).
</para>
<para>
-If you prefer to leave a more evident trace of your sponsorship job, you can
-add a line stating it in the most recent changelog entry.
+You might want to check out the Package Tracking System (see <xref
+linkend="pkg-tracking-system"/>) to verify if the
+maintainer has not missed something important. Maybe there are translations
+updates sitting in the BTS that could have been integrated. Maybe the package
+has been NMUed and the maintainer forgot to integrate the changes from the
+NMU in his package. Maybe there's a release critical bug that he has left
+unhandled and that's blocking migration to <literal>testing</literal>. Whatever. If you find
+something that she could have done (better), it's time to tell her so that
+she can improve for next time, and so that she has a better understanding
+of her responsibilities.
</para>
<para>
-You are encouraged to keep tabs on the package you sponsor using <xref
-linkend="pkg-tracking-system"/> .
+If you have found no major problem, upload the new version. Otherwise
+ask the maintainer to provide you a fixed version.
</para>
</section>
+</section>
-<section id="s7.5.3">
+<section id="advocating-new-developers">
<title>Advocating new developers</title>
<para>
See the page about <ulink
</para>
</section>
-<section id="s7.5.4">
+<section id="become-application-manager">
<title>Handling new maintainer applications</title>
<para>
Please see <ulink url="&url-newmaint-amchecklist;">Checklist