technology from back to front

Getting into Debian

mercurial-server is an official Debian package! Right now it’s only in the “unstable” distribution, but all being well it will slowly percolate forward, first into “testing”, then eventually into the stable distributions of not only Debian but Ubuntu and other Debian-based systems.

Getting it into Debian was quite a long and strange process; the care that Debian takes over package quality puts quite a burden on individual developers in order to minimize the burden on overworked Debian staff. I’ll talk through the steps I took here, eliding over any wrong turns of course, in the hope that the way I did it might be useful to others.

One particular curiosity is that everything you read assumes that you’re starting with a bit of software written by someone else, called the “upstream” author, and that you have a lot of work to do to co-ordinate what you’re doing with their work because they are totally oblivious to you and to Debian. Of course, in this instance the upstream author is me, but the way the Debian process is set out you have to keep your upstream hats and Debian hats separate, so that things don’t get crossed over if someone else has to take the Debian hat off you in order to for example do a non-maintainer upload. (So-called “Debian native” packages – packages that only make sense in the context of Debian – are exceptions to this). In what follows I’ll assume that like me, you are your own upstream; frankly I think it would be somewhat bizarre to want to maintain some Unix software but have no care for the majority of potential users who run a Debian-based system like Ubuntu and would like to install it conveniently.

You should of course be using a modern VCS which supports branching and merging properly. Unsurprisingly I used Mercurial; if your VCS doesn’t support the sort of operations I set out here you should probably switch to a better one.

Sources of advice

There are several manuals published by the Debian project aimed at those making Debian packages. The only one you’re likely to read all the way through is the Debian New Maintainer’s Guide, but you’re likely to refer to the others many times.

I don’t think I would have succeeded without the help I got from IRC. I got a lot of good answers on the #debian-mentors channel, but it looks like I should have made more use of #debian-devel. One of the nice things about IRC is that it’s a good place not just for advice on how to fix specific problems, but also for opinions on what the Right Thing is.

Intent to Package

The first thing you should do is file an Intent to Package (ITP). This is a bug against the Debian pseudo-package Work-Needing and Prospective Packages (WNPP) that tells other developers that you are planning on packaging a particular piece of software, in case anyone else was thinking of doing the same thing. Of couse if someone else was thinking of packaging your software you as the author might already know about it, but since this step is mandatory you might as well do it early.

As far as I can tell, the only way to report bugs in Debian is by email. You can either use reportbug, or compose the email yourself. I tried to use reportbug, which is the recommended way, but email isn’t set up on my machine so it didn’t work out. If “echo foo | mail you@your.address” works for you (and your address isn’t local) then reportbug makes life easier. In the end I used reportbug to compose what I wanted to send, then when it threw me into the editor I copied and pasted what it gave me into a Thunderbird email, which worked fine. My ITP took 30 minutes to process, so be patient.

Debianizing your package

Debian distributes package sources in two parts: an “.orig.tar.gz” file representing the original upstream sources, and a “.diff.gz” file representing the changes made to adapt the package for Debian. In our VCS, the “default” branch represents the “upstream” version of the package, and the “debian” branch represents our changes to support Debian. This makes it easy to keep the two separate while carrying over changes in the upstream version into the Debian version.

Since you’re the upstream author, you should be able to ensure that the only difference between the two is the presence of the “debian” directory in the Debian version. In fact, if you do need to introduce a difference between the two, simply allowing the “.diff.gz” file to make the change is no longer the recommended means; rather, the “.diff.gz” should create patch files under the “debian” directory which the packaging process will run as part of the process of creating the package, using a system such as dpatch or quilt. This would also demand greater cleverness on how you use the VCS, which is beyond the scope of what I’ve tried so far.

For details on how to Debianize your package you’ll have to refer to the docs above or have a look at how mercurial-server does it, but here’s a few useful pointers:

- If changing the upstream package makes your life easier without compromising its non-Debian nature, do it.
- Use “dh(1)”, the new do-everything rule in debhelper, which makes your rules file much shorter. This means your package won’t build in Debian Lenny, but new packages should in any case target “unstable”.
- Use the nice new control fields, like Homepage, Vcs-Browser, Vcs-Hg

Building the package

To build a Debian package, you have to create a GPG key you’ll use to sign packages. I created a new one explicitly for software signing.

You need a changelog entry for the build; the best way to create one is by running “debchange”.

EMAIL=paul@lshift.net debchange --create --package mercurial-server -D unstable -v 0.9-1 --closes 555750

Here’s the script I run to do the build:

#!/bin/sh

set -e

# FIXME: un-hard-code these
PACKAGE=mercurial-server
UPSTREAM_VERSION=0.9
DEBIAN_VERSION=${UPSTREAM_VERSION}-1
UPSTREAM_TAG=release_${UPSTREAM_VERSION}
DEBIAN_TAG=debian_${DEBIAN_VERSION}
#UPSTREAM_TAG=default
#DEBIAN_TAG=debian
BUILDDIR=build/debian

rm -rf ${BUILDDIR}
mkdir -p ${BUILDDIR}
hg archive -X '.hg*' -t tgz -r ${UPSTREAM_TAG} \
   ${BUILDDIR}/${PACKAGE}_${UPSTREAM_VERSION}.orig.tar.gz
hg  archive -X '.hg*' -r ${DEBIAN_TAG} \
 ${BUILDDIR}/${PACKAGE}-${UPSTREAM_VERSION}
cd ${BUILDDIR}/${PACKAGE}-${UPSTREAM_VERSION}
dpkg-buildpackage -kFD56DDC0
cd ..
lintian -i --pedantic -IE ${PACKAGE}_${DEBIAN_VERSION}_*.changes
sudo pbuilder --build ${PACKAGE}_${DEBIAN_VERSION}.dsc

This puts both the upstream and Debian versions of the package into a build directory based on VCS tags, runs the builder against them (which then generates not only the binary .deb file but also the various files associated with Debian sources files: a “.diff.gz” and a signed “dsc” description file and “changes” file. It then runs Lintian against it set to its most pedantic level, and uses “pbuilder” to check that the Build-Depends field is correct. If I get the time, a future incarnation of this might also install the package on a virtual machine and run some tests, but that’s a way away yet.

There is also a package called “hg-buildpackage” for building Debian packages from Mercurial, but at a glance it seems to be fairly “mq” oriented and I’m not an mq fan.

Finding a sponsor

If you’re reading this, you’re not an official Debian developer. That’s OK, neither am I; becoming an official Debian developer is a long and slow road and I don’t know if I want to start yet. You don’t need to be a Debian developer to develop for Debian, but you will need one to help out: to “sponsor” your package.

Before you start asking for a sponsor, double, triple check that everything with your package is OK. Sponsors aren’t volunteering to shoulder lots of work, but to check that you’ve done the right thing, and it’s work for them if the checks don’t work out. See this list of sponsor checklists for the sort of things that sponsors might ask of you. You don’t have to do everything on every list – indeed, some of the requirements contradict each other, so you can’t – but you should have a good reason for not doing one of those things, and bear in mind that each thing you decide not to do means at least one potential sponsor who won’t be taking up your package.

mentors.debian.net

Your search for a sponsor starts with mentors.debian.net

- Create an account on mentors.debian.net, and upload your GPG public key

- Use software such as “dput” to put the latest version of your package onto the server

- Look at “My packages”, and check the box that says you are seeking a sponsor

- Ask for the RFS template, fill out the fields, and mail it to debian-mentors. Remember to ask people to Cc any responses to you, unless you decide to subscribe to the list.

- Wait for a sponsor to step forward.

Cheating

After all this, my next step was to cheat: I posted to the LShift blog and to my personal blog asking for a Debian developer to volunteer to sponsor the package. Obviously you should also cheat as much as possible in this regard – post to the project’s web page, or mailing list, or similar. This worked within half an hour for me, as my friend Steve Kemp stepped forward to volunteer; I got a second offer a few days later as a result of my post to the Mercurial mailing list.

Success!

Naturally, despite my best efforts there were a couple of issues to be sorted out with the package before it was ready to upload, so we went around the loop once to produce version 0.9 before making the upload, but happily he was able to put the package into Debian within a day of my initial call for sponsors. After that it was just a question of waiting – the package was uploaded to ftp-masters on 2009-11-12, and I got the email telling me I’d hit Debian unstable on 2009-11-25. Ten days from that date, if there are no problems, it should move into Debian “testing”, and it will hopefully make its way into the next stable Debian distribution, the Ubuntu “universe” component, and to the world of Linux users everywhere.

I’ve been using Debian since 1995, and I’ve always been incredibly grateful to the army of developers and other hard working people who make it possible. I’m very proud to have finally given some small thing back to the project I’ve been making such use of for so long. Now to do it all over again for Rurple

by
Paul Crowley
on
01/12/09
  1. Congratulations, Paul! and thanks for the summary. Comparing what you’ve ended up with with the RabbitMQ debianish packaging process is interesting: I think we should (sometime) switch to a way of doing things more like that you describe. In particular, your tip about using dh is a gem.

  2. [...] over any wrong turns of course, in the hope that the way I did it might be useful to others. More here mercurial-server is an official Debian package! Right now it’s only in the “unstable” [...]

  3. Kumar Appaiah
    on 10/12/09 at 4:32 am

    Very nice post! The bug tracking system is the next step. Also, I bet you’ll get some translation help and suggestions from Debian users (through the BTS); especially if you have a significantly used package like mercurial-server.

    Thank you for taking the time and effort to contribute to Debian.

 
 


+ 7 = sixteen

2000-14 LShift Ltd, 1st Floor, Hoxton Point, 6 Rufus Street, London, N1 6PE, UK+44 (0)20 7729 7060   Contact us