How to maintain your package in bzr

This page sets out how to begin maintaining an Ubuntu source package using our bzr revision control system. If you want to work on a source package that is already maintained using bzr, see the BzrContributorHowto page instead.

Knowledge of how to use bzr is assumed to keep this simple to follow.

It's also assumed that you have a Launchpad account (after all, you're an Ubuntu maintainer) and that you've registered your SSH public keys there so you can use the Launchpad codehosting service.

Registering your package

The most important thing to do first is to register the package so that other people can find your revision control branch. If people are not able to find the branch, they may not realise it is maintained in revision control in the first place, and may upload directly to the archive without making their changes available properly.

Register the product in Launchpad

Branches in Launchpad are registered against products, so you need to make sure there is a product ready for it. If this is a new native source, you'll probably have to register it.

Make sure other developers know about it

You should add a new field to debian/control that points to the code.launchpad.net branch that hosts the uploaded packages. It should look similar to:

Please make sure that you use the code.launchpad.net address, not the bazaar.launchpad.net one. The former redirects to the latter for the actual bzr commands, but also provides a nice web interface.

Other maintainers need to check for this field with apt-cache showsrc package before using apt-get source package, to avoid uploads which diverge the state of the bzr branch and the current version in the archive. In Gutsy and later, apt will check this automatically on apt-get source.

If there are already similar fields from Debian, they should be removed to avoid confusion.

In earlier times, the BzrMaintainedPackages wiki page listed the packages being maintained in bzr. Until all source packages listed there have a Vcs-Bzr header, you should also check this page before working on a package.

Branch layout

Native Ubuntu packages

This is the simplest case. Just bzr init the root source directory, bzr add everything relevant (i. e. all files which are not automatically generated during build). Such packages do not have separate patches.

If the project is Ubuntu specific and includes all the packaging files, the branch name should be ubuntu for the trunk. If you create branches for the versions in stable releases, these should be called like the Ubuntu release (like feisty).

If the project is not Ubuntu specific and other distributions want to use it too, you should register the branch as trunk, and create another branch ubuntu which adds the packaging bits on top of it. Code development happens on trunk, which is just merged into ubuntu whenever appropriate (such as when a new upload is prepared).

Packaging-only branches

The large majority of packages have an external upstream. The most practical workflow today is to just keep the debian/ directory under revision control and handle changes to the upstream code as patches. This is a very popular, bandwidth efficient, and reasonably clean method of package maintenance and common practice in Debian as well.

However, they are not supported by Launchpad's automatic svn-to-bzr import service, so if you want to base your work on a Debian package on alioth which is maintained in an SVN branch, you need to use bzr-svn yourself and manually register packaging-only bzr branches in Launchpad (import the Debian source into debian and branch off ubuntu).

Many tools like devscripts assume that the source tree root itself is a branch, and working like that is a bit more comfortable and compatible to the other two layouts described here. So while having the debian/ directory be a branch by itself would be cleaner (since it avoids a lot of unknown files), it makes maintenance a bit harder.

So, the steps to turn an upstream foo_1.0_orig.tar.gz into a bzr-maintained package:

All changes you do to the package only happens in debian/. See How to patch packages for more information about how to apply changes to the upstream parts. Thus, when you update to a new upstream version foo_2.0_orig.tar.gz, you throw away everything but debian/ and unpack the new tarball. Starting from a clean source tree root, this looks like:

Upstream in revision control

If you want to keep the upstream part in bzr, the following branch layout is recommended:

When a new upstream release is out, simply import and commit that into the upstream branch and merge from it.

However, this workflow is quite impractical as long as Launchpad does not have many upstream imports yet and does not have a smart server running. Also, to keep track of distribution code changes, bzr needs to grow a concept of stacked branches. The NoMoreSourcePackages specification describes a loom plugin design which will provide this functionality.

Changelog housekeeping

Document each change in the changelog using dch and commit it using debcommit (in the devscripts package). This will automatically generate an appropriate bzr log entry from the debian/changelog entry.

While you work on a package, the distribution in debian/changelog should be set to UNRELEASED. When it is time to do an upload, change this to the relevant target release (such as feisty) and note down the release in the bzr log, so that you can find it easily in the future:

This approach is especially important if several people work on a package. If the target is not UNRELEASED it indicates that the next contributor needs to start a new version with dch -i instead of just appending new stuff to the current version.

Pushing the first version

When you're ready to push the first version up, this might be right after running bzr init or may be when you first upload, you need to make a decision about who else can work on it.

Now push your branch to Launchpad using the following URL form:

Where:

e.g.

Note that there needs to be some time (roughtly 15 minutes) between the creation of the Project and the initial bzr push. Earlier attempts may fail since the Project has not yet had time to be created on the bazaar servers.

Uploading

Uploading is just a matter of running dpkg-buildpackage as usual. You may want to strip out the .bzr directories, or you may not -- there are advantages to both. I'd suggest just using pristine upstream tarballs rather than trying to generate them from the upstream branch.

Be sure to commit and push any debian/changelog changes you make.

Linking the Product and Source together

Once the first version has been uploaded, you should make sure that the product and source package are linked together in Launchpad. If you're importing a source package that already exists, you can do this at any time, e.g. when you locate or register the product.

This is not related to the actual branches -- this is simply a step to make sure that Launchpad can provide a link to the product when you look at the source package.

There's often confusion about what Release Series mean, so here's two quick examples.

BzrMaintainerHowto (last edited 2009-06-03 16:39:02 by athedsl-252018)