Best practices when sponsoring Debian packages

Sponsoring a package means uploading a package for someone else (usually a new contributor starting out as package maintainer). This is an activity reserved to Debian Developer who are supposed to be knowledgeable about packaging. This article tries to document the process to ensure the sponsor is doing a reasonably good job according to Debian’s standards.

Sponsoring a package in the Debian archive is not a trivial matter. It means that you verified the packaging and that it is of the level of quality that Debian strives to have. Let’s have a look to what you can and should do when you’re sponsoring a package.

Sponsoring the initial upload

Sponsoring a brand new package into Debian requires a thorough review of the Debian packaging. Building the package and testing the software is definitely not enough! You should open every file in the debian directory and look out for potential problems. Here’s a checklist that you can use to perform the audit:

  • 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).
  • Run lintian. It will catch many common problems. Be sure to verify that any lintian overrides setup by the maintainer is fully justified.
  • Run licensecheck and verify that debian/copyright seems correct and complete. Look for license problems (like files with “All rights reserved” headers, or with a non-DFSG compliant license).
  • Build the package with pbuilder (or any similar tool) to ensure that the build-dependencies are complete.
  • Proofread debian/control: does it follow the best practices? are the dependencies complete?
  • Proofread debian/rules: does it follow the best practices? do you see some possible improvements?
  • 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)?
  • Review any change to upstream files (either in .diff.gz, or in debian/patches/ or directly embedded in the debian tarball for binary files). Are they justified? Are they properly documented (with DEP-3 for patches)?
  • 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 described by the Developers Reference?
  • Build and install the packages, try the software. Ensure you can remove and purge the packages. Maybe test the packages with piuparts.

If the audit did not reveal any problem, you can upload the package. 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 Package Tracking System.

Sponsoring an update of an existing package

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.

To be able to analyze the difference you need both versions. Download the current version of the source package (with apt-get source) and rebuild it (or download the current binary packages with aptitude download). Download the source package to sponsor (usually with dget).

Read the new changelog entry, it should tell you what to expect during the review. The main tool you will use is debdiff, 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).

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 filterdiff -i '*/debian/*'), you must understand all the changes you see and they should be properly documented in the Debian changelog.

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.).

You might want to check out the Package 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.

If you have found no problem, upload the new version. Otherwise ask the maintainer to provide you a fixed version.


This article will be repurposed to enhance the Debian Developers Reference, hopefully leading to a fix for the wishlist bug #453313. Click here and help me fix more of those.

You’re also welcome to suggest improvements in the comments. Are there other checks that you’re always doing? Do you have some handy tip to make it easier to review a package?

Additional Resources

Get the Debian Administrator's Handbook

After a successful liberation campaign, the Debian Administrator's Handbook is now freely available. If you appreciate my articles and what I do for Debian, check out the book and grab a copy.

Comments

  1. More of that stuff here, I’ve added a link back to this page:

    http://wiki.debian.org/SponsorChecklist

    • Thanks Paul, I was not aware of that wiki page.

      Reading it, I think it’s interesting to add some words about whether the package is good enough to be in Debian and whether the maintainer is capable of doing the work.

      BTW, I found Pierre Habouzit’s checklist very well done: http://people.debian.org/~madcoder/sponsor.html

      It frames the issue of sponsorship vs joining Debian in a positive way and the technical advices are sound.

  2. Regarding the completeness of debian/copyright: grep -ir ‘copyright’ sometimes reveals copyright statements in rather uncommon places.

  3. Being boring and paranoid: never build package from untrusted (whom could we trust at all? ;-) ) mentoree/upstream in the environment having access to your sensitive information (such as ssh/gpg keys).

    More on the topic: recent question/discussion
    Securing/monitoring Debian devel environment
    http://lists.debian.org/debian-devel/2010/12/msg00374.html

  4. The one thing missing from all these sponsoring guidelines is: how to actually build and upload the package correctly, with cowbuilder, so that it shows up on my QA page as sponsored upload, the sponsored guy gets all the credit, etc.

    • The developers reference already covers the part concerning the build although it doesn’t recommend cowbuilder or any stuff like that. Basically you just pass “-k” to dpkg-buildpackage and you let the sponsoree name everywhere (and yours nowhere, it will be deduced from the signature for the QA page).