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 SFTP "supermirror".

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.

• Find the product at https://launchpad.net/products

• Create new products at https://launchpad.net/products/+new

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:

•  XS-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-chache 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 the future, [https://launchpad.net/bugs/115959 apt will check this automatically].

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.

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 onto the super-mirror using the following URL form:

• sftp://$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 sftp://kamion@bazaar.launchpad.net/~ubuntu-core-dev/ubiquity/ubuntu

Non-native packages?

The large majority of packages have an external upstream.

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 [https://answers.launchpad.net/launchpad-bazaar/ requested in an answer ticket] (hopefully this [https://launchpad.net/bugs/115965 gets easier in the future]).

• Branch this, apply the Ubuntu changes, 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 might be impractical as long as Launchpad does not have many upstream imports yet and does not have a smart server running. So you might alternatively decide 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 clean method of package maintenance and common practice in Debian as well. However, you should make the debian/ directory a branch by itself instead of having the top level directory be the branch and add the single debian/ directory to it; this avoids a lot of unknown files and is future-proof in case you ever want to move the upstream parts to revision control.

Packages with patches?

And what about packages with multiple things in debian/patches? I suggest the following URL form /ubuntu.$PATCH for each patch.

Make sure the branch description (editable once pushed) contains the filename of the patch that should be generated from it.

A tool to make these easier will appear very shortly.

Debian-derived packages?

You can do these in the same way as non-native above, except import the Debian source using /debian and branch for /ubuntu. A lot of packages are maintained on [http://alioth.debian.org/ alioth] in an [http://svn.debian.org/ SVN branch]. Just request an automatic bzr import to Launchpad if you want to work on these.

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.