= 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 [[http://bazaar-vcs.org/Documentation|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.

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

  {{{ 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, [[https://launchpad.net/bugs/115959|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 [[http://alioth.debian.org/|alioth]] which is maintained in an [[http://svn.debian.org/|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 [[PackagingGuide/PatchSystems|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 [[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 (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.