chiark / gitweb /
Rework section on "sponsoring packages" and include a basic checklist for the sponsor...
authorhertzog <hertzog@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Sun, 20 Feb 2011 09:52:45 +0000 (09:52 +0000)
committerhertzog <hertzog@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Sun, 20 Feb 2011 09:52:45 +0000 (09:52 +0000)
git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@8521 313b444b-1b9f-4f58-a734-7bb04f332e8d

beyond-pkging.dbk
common.ent
debian/changelog

index cafbbd3..f9b5a9b 100644 (file)
@@ -326,85 +326,231 @@ describes how to help new prospective developers.
 <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 (.dsc) and puts it online
+somewhere (like on mentors.debian.net). Or even better, she provides
+a link to a <xref linkend="servers-vcs">public VCS repository</link> 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.
+But 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 userbase? 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: several developers share their own
+sponsorship checklists at <ulink url="http://wiki.debian.org/SponsorChecklist"/>.
+</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 lintian (see <xref linkend="lintian"/>). It will catch many common
+problems. Be sure to verify that any lintian overrides setup by the
+maintainer is fully justified.</para>
+</listitem>
+<listitem>
+<para>Run licensecheck (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 pbuilder (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 (preinst, postinst, prerm, postrm,
+config): will the preinst/postrm 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 .diff.gz, or in
+<filename>debian/patches/</filename> or directly embedded in the debian
+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 piuparts.
 </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. But 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 modifiy the source package to put your name
+in the changelog or in the control 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 dpkg-buildpackage to use your key for
+the signature. You do that with the -k option:</para>
 <screen>
 dpkg-buildpackage -k<replaceable>KEY-ID</replaceable>
 </screen>
+<para>If you use debuild and debsign, 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 devscripts package), you can run it with two source packages (.dsc
+files), or two binary packages, or two .changes files (it will then
+compare all the binary packages listed in the .changes).
 </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 debdiff
+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 testing. 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
@@ -413,7 +559,7 @@ developer</ulink> at the Debian web site.
 </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
index c33b9cf..4725f0e 100644 (file)
@@ -92,6 +92,7 @@
 <!ENTITY url-i18n-intro "http://&www-debian-org;/doc/manuals/intro-i18n/">
 <!ENTITY url-ddtp "http://ddtp.debian.net/">
 <!ENTITY url-l10n "http://&www-debian-org;/intl/l10n/">
+<!ENTITY url-dep3 "http://dep.debian.net/deps/dep3/">
 
 <!ENTITY url-incoming "http://incoming.debian.org/">
 <!ENTITY url-testing-maint "http://www.debian.org/devel/testing">
index ed5f6d8..4b520bc 100644 (file)
@@ -4,6 +4,10 @@ developers-reference (3.4.5) UNRELEASED; urgency=low
   * Remove part about -v for package uploads from experimental to unstable,
     version tracking removed that requirement.
 
+  [ Raphaël Hertzog ]
+  * Rework section on "sponsoring packages" and include a basic
+    checklist for the sponsor. Closes: #453313
+
  -- Raphaël Hertzog <hertzog@debian.org>  Wed, 24 Nov 2010 23:54:39 +0100
 
 developers-reference (3.4.4) unstable; urgency=low