Contributor Documentation

7 mistakes to avoid when participating to Debian mailing lists

February 24, 2011 by Raphaël Hertzog

You’re eager to start contributing to Debian, your first action is to subscribe to some high-profile mailing lists (like debian-devel and debian-project) to get a feel of the community. You read the mails for a few days and then you find out that you could participate to the discussions, it’s a simple first step after all. True enough.

That said, it’s not as easy as it looks like. There are many mistakes that you should avoid:

Don’t fall in the trap where your mailing list participation is your sole contribution to Debian. If you want people to give credit to your messages, you should already be doing something else for Debian.
Don’t participate more than once a day to a given thread. There are many people subscribed, you should leave room for other people to express their point of view. You can always follow up one day after and reply to several messages at once if you believe you still have something new to add to the discussion.
Don’t reply to off-topic threads. Someone asked a simple question and someone else pointed out that his message was off-topic. Don’t reply, or if you really need to, do it on the correct list or with a private response.
Don’t ask questions unless it’s useful to bring the discussion forward. Development lists are not here to fill the gaps in your knowledge. We already have debian-mentors for this. Furthermore there’s no better way to learn than to find yourself the answers to your questions. 🙂
Don’t believe your opinion is so important. We’re all very opinionated and discussions that consist only of contradicting opinions tend to go nowhere. Thus don’t give your opinion unless you can back it up with new facts or another experience.
Don’t participate to all threads. There are surely some topics where you are more knowledgeable than others, participate where you add the most value and leave the others threads to the other experts (and learn by reading them).
Don’t hide your identity. In Debian we like to know each other. Use your real name and not some anonymous nickname. You need to be able to stand up behind your words, otherwise you’re not credible.

I have myself been guilty of several of those when I started… I invite you to follow my recommendations to ensure our mailing lists remain pleasant to read and an effective discussion place.

You should follow me on Identi.ca, Twitter and Facebook. Or subscribe to this blog by RSS or by email.

Best practices when sponsoring Debian packages

February 10, 2011 by Raphaël Hertzog

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?

3 ways to not clutter your Debian source package with autogenerated files

January 28, 2011 by Raphaël Hertzog

It’s quite common that the upstream build system generates/updates some files but does not clean them up properly when you call make clean. In that case, when you rebuild the package a second time in the same tree, the generated Debian source package will contain those changes.

You usually don’t want those changes. They make your package harder to review because they contain unneeded modifications (either directly in the .diff.gz with the old source format, or in a new patch in debian/patches/debian-changes-<ver> with the “3.0 (quilt)” source format).

I’ll show you 3 ways to avoid this problem. They are all workarounds, the proper fix would be to improve the upstream build system to really clean up the generated files. This is usually possible for files that are “created”, but it’s much more cumbersome for files that are “updated” (you would have to keep a backup of the original file so that you can restore it).

The traditional fix

Instead of relying on the upstream build system to do the work, we modify the clean target in debian/rules to remove the files that are left-over. Since “debian/rules clean” is always called before a source package is built, those generated files are not included as changes compared to what upstream provided.

A common work-around: always build from a clean state

As you have noted, the problem only happens when you build (source and binaries) twice in a row in the same tree. Some VCS-helper tools always build the Debian package in a temporary tree which is exported from the VCS. This is the case of svn-buildpackage by default and of git-buildpackage if you use its --git-export-dir option.

I don’t like this solution because it solves the problem only for the maintainer. Anyone else who is working on top of the package without using the same VCS-helper tool would be affected by the problem.

A new way to avoid the problem

Since it’s now possible to store dpkg-source options in the source package itself, we can conveniently have everybody use the --extend-diff-ignore option. It tells dpkg-source to ignore some files when checking whether we have made changes to upstream files.

For example if you want to ignore changes made on the files “config.sub”, “config.guess” and “Makefile” you could put this in debian/source/options:

# Don't store changes on autogenerated files
extend-diff-ignore = "(^|/)(config\.sub|config\.guess|Makefile)$"

You need to know a bit about Perl regular expressions since that’s what is used by dpkg-source to match the filenames to exclude.

Note that this approach always works, even when you can’t remove the file. So it saves you having to make a backup of the unmodified file just to be able to restore it before the next build.

Found it useful? Be sure to not miss other packaging tips (or lessons), click here to subscribe to my free newsletter and get new articles by email.

Avoid a newbie packager mistake: don’t build your Debian packages with dpkg -b

December 17, 2010 by Raphaël Hertzog

In the last years, I have seen many people try to use dpkg --build to create Debian packages. Indeed, if you look up dpkg’s and dpkg-deb‘s manual pages, this option seems to be what you have to use:

-b, --build directory [archive|directory]

Creates a debian archive from the filesystem tree stored in directory. directory must have a DEBIAN subdirectory, which contains the control information files such as the control file itself. This directory will not appear in the binary package’s filesystem archive, but instead the files in it will be put in the binary package’s control information area.

And indeed, dpkg-deb is what ultimately creates the .deb files (aka binary packages). But it’s a low-level tool that you should not call yourself. If you want to properly package a new software, you should rather create a Debian source package that will transform upstream source code into policy-compliant binary packages.

Creating a source package also involves preparing a directory tree (but with a “debian” sub-directory), it’s probably more complicated than calling dpkg -b on a manually crafted directory. But the result is much more versatile: the tools used bring value by dynamically analyzing/modifying the files within your package (for example, the dependencies on C libraries that your package needs are automatically inserted).

If this is news to you, you might want to check out the New Maintainers’ Guide and the Debian Policy.