<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,bz2,lzma}</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>
+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>
+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>
-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.
+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>
-Once the package meets Debian standards, build and sign it with
+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>
-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.
+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>
-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. The sponsoree will therefore get all the BTS mail about
-the package.
+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>
-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.
+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>
-You are encouraged to keep tabs on the package you sponsor using <xref
-linkend="pkg-tracking-system"/>.
+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>
+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>
+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>
+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
~ianmdlvl / developers-reference.git / blobdiff