= How to contribute to a package maintained in bzr =

This page describes how you should contribute to an Ubuntu source package that is maintained using our bzr revision control system.  If you want to begin maintaining a source package using bzr, see the BzrMaintainerHowto page instead.

Knowledge of [[http://doc.bazaar-vcs.org/latest/en/mini-tutorial/|how to use bzr]] is assumed to keep this simple to follow.

It's also assumed that you:

 * have an [[https://launchpad.net/+login|account]] on LaunchPad (after all, you're an Ubuntu developer) and that
 * have [[https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair|registered your SSH public keys]] there so you can use the LaunchPad codehosting service
 * have already installed the bzr package onto your own local computer (using `sudo apt-get bzr` or equivalent).

== Find the package ==

The list of source packages currently maintained with bzr is published at BzrMaintainedPackages.  If the package is not on this list, you should contribute the old-fashioned way.

When you have located the package on the list, select it and it will show you the list of all the available branches for that product.

== Get a copy ==

The branch you want is the `ubuntu` one owned by `ubuntu-core-dev` (for main packages) or `ubuntu-dev` (for universe packages).  Get a copy of that using `bzr branch`

 * If you are a member of the owning team, you should use the `sftp` url.

 * If you are not a member of the owning team, you may still contribute!  Get the branch using the `http` url instead.

=== Multi-branch packages ===

Some packages may have multiple patch branches (noted by `ubuntu.$PATCH`), you may want to get these as well if you intend to work on a particular patch.  If you're adding a new patch, you should get the `/ubuntu` or `/upstream` branch instead.

The description of the branch will tell you what the filename of the patch should be.

== Publishing your changes ==

Remember to commit your changes locally (using `bzr commit`) first.

If you are a member of the owning team, and it's ready for upload, you can simply push your changes to the same branch you grabbed the package from.

If you are not a member, or wish to create your own branch anyway, you should instead push to your own private branch.  Use the following URL form:

 `bzr+ssh://$USER@bazaar.launchpad.net/~$USER/$PRODUCT/ubuntu.$NAME`

Where:

 * `$USER` is your launchpad user-id.
 * `$PRODUCT` is the launchpad name of the product
 * `$NAME` briefly describes the reason for the branch

e.g.

 `bzr push bzr+ssh://tfheen@bazaar.launchpad.net/~tfheen/ubiquity/ubuntu.bug12345`

This will show up in the packages list for the product automatically.

 * Keep in mind that a bzr push via sftp requires the python-paramiko package.

=== New patches? ===

If the branch was one of those with a new patch, you should push to an appropriate `$NAME` for the patch and make sure that the patch filename is known and will be applied.

== Requesting a merge ==

If you are not a member of the owning team, you cannot directly upload your contributions.

Instead link to your branch URL (available from the products page once you have pushed) in the bug associated with the branch.  If there is no open bug, file one (it probably should be wishlist).

A developer can then easily merge your changes and upload them.

== Further Reading ==

 * More [[http://bazaar-vcs.org/Documentation|in-depth documentation]] about `bzr` itself
 * [[https://help.launchpad.net/Code|Help about code hosting]] in LaunchPad
 * The Bazaar project's tutorial [[http://doc.bazaar-vcs.org/latest/en/tutorials/using_bazaar_with_launchpad.html|Using Bazaar with Launchpad]]