BzrMaintainerHowto

Revision 21 as of 2008-08-06 16:16:49

Clear message

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:

  •  Vcs-Bzr: https://code.launchpad.net/~ubuntu-core-dev/apport/ubuntu 

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 XS-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:

  • tar xzf foo_1.0_orig.tar.gz

  • cd foo-1.0

  • mkdir debian

  • bzr init

  • Put the packaging bits into debian/, including all the debian/patches/ files you want to apply.

  • bzr add debian

  • bzr commit -m "initial packaging"

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:

  • ls | grep -wv debian | xargs rm -rf

  • tar xzf ../foo_2.0_orig.tar.gz --strip-components=1

  • dch -v2.0 -D UNRELEASED and add an appropriate changelog

  • Check that the patches still apply, remove the obsolete ones and update the others to the new upstream version.

Upstream in revision control

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

  • Import the upstream source into one branch and call it upstream. Alternatively, automatic imports from foreign SVN or CVS should be requested in an answer ticket (hopefully this gets easier in the future).

  • Branch this, apply the Ubuntu changes (including the packaging in debian/), and push it as ubuntu branch.

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:

  •  bzr commit -m "release as 1.2.3-4ubuntu5 to feisty" 

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.

  • If the package is intended for main, then the team should be ubuntu-core-dev.

  • If the package is intended for universe, then the team should be ubuntu-dev.

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

  • bzr+ssh://$USER@bazaar.launchpad.net/~$TEAM/$PRODUCT/ubuntu

Where:

  • $USER is your launchpad user-id.

  • $TEAM is the team that will own the branch.

  • $PRODUCT is the launchpad name of the product you found or registered.

e.g.

  • bzr push bzr+ssh://kamion@bazaar.launchpad.net/~ubuntu-core-dev/ubiquity/ubuntu

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.

  • Go back to the product page you found earlier.
  • Pick the appropriate Release Series of the product (they're listed on it)
    • This reflects the lines of upstream development, you do not need a series to mean "ubuntu changes".

    • Freshly registered products have a main/trunk series created automatically. Use that.

    • If the product has multiple lines of development, and can be packaged multiple times, for certain large projects (e.g. Apache) it may be appropriate to create a new one. Use the "Add Release Series" (/+addseries) link in the porlet if you need to. If you're not sure whether you need a new series or not, you do not!

  • From the Release Series package, click "Link to Ubuntu Package" (/+ubuntupkg) in the portlet.

    • For existing products you'll probably find it is already linked to an Ubuntu source package. It does not matter if this is for an older Ubuntu release, as long as the source package name is correct. if so, skip the next step.
  • Enter the source package name.

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

  • The pmount product has one release series, main because it's developed as a single line upstream. That main series is linked to the Ubuntu pmount source package. Thus "the main development line of pmount is packaged in Ubuntu in the pmount source package".

  • The apache product has three release series, 1.13, 2.0 and 2.2 to reflect the different development lines upstream. The 1.13 series is linked to the Ubuntu apache source package, the 2.0 series is linked to the Ubuntu dapper apache2 source package, and the 2.2 series is linked to the Ubuntu edgy apache2 source package.