Life with bzr and Launchad

Work flow examples

Getting set up

The metadata of a bzr commit contains a name and e-mail of the author and committer (usually the same, but can differ). So, you need to let bzr know who you are:

$ bzr whoami "Soren Hansen <soren.hansen@rackspace.com>

This will set this user id globally. It can be set on a per-branch basis as well using the --branch option while in the relevant branch:

$ bzr whoami --branch "Soren Hansen <soren@ubuntu.com>"

This is useful if you have more than one affiliation.

To make the most of the Launchpad integration, you also tell bzr your Launchpad id:

$ bzr lp-login soren

Now you're ready to rock and roll!

A day in the life of a bzr user

Note: We're walking through all of the bits here for completeness, some of the workflow elements are already automated, or are in the process of being automated away)

bzr keeps it branch data in a .bzr in the top level of your source tree. If you expect to have more than one branch of a project (which is usually the case), you start out by creating a top level directory for the project:

$ mkdir ~/src/novacc
$ cd ~src/novacc

Now, let bzr know that it should use this for data shared between the individual branches:

$ bzr init-repo .

Without this, bzr would copy all the branch data when you create a new branch, so this saves time and space.

Now, check out the project:

$ bzr branch lp:novacc

This will grab the designated trunk branch of novacc from Launchpad.

The typical workflow from here is to create a branch specific to the feature or bug you're about to work on. Say we want to work on bug number 765432 on Launchpad and we're not creative enough to come up with a descriptive name for the branch:

$ bzr branch novacc lp765432

This will create a new directory, lp765432, with a new working tree in it, ready for hacking.

$ vim novacc/endpoint/api.py
<hack> <hack>
$ bzr commit --fixes lp:765432 -m 'Updated the url argument sort method to ensure a C locale while sorting.'

Note: If you omit the -m argument, bzr will open up an editor for you to enter a message, as you would expect.

So far, this branch only lives locally. You want it reviewed, so you push it to Launchpad:

$ bzr push lp:~soren/novacc/lp765432

Every user, affiliated with the project or not, can push a novacc branch to Launchpad. No special permissions are required. The general URL form is:

lp:~username/projectname/branchname

Once it's been pushed, Launchpad will notice the fact that we specified "--fixes lp:765432" while committing and show a link to the branch in the bug. Anyone subscribed to the bug will get an e-mail about this update.

The branch is immediately visible on Launchpad at https://code.launchpad.net/~soren/novacc/lp765432. You can also get a listing of all of your branches for a particular project at https://code.launchpad.net/~soren/novacc

Note: it's also possible to manually link a bug to a branch from the Launchpad web interface. This is occasionally handy if the bug is tricky and takes a while to fix, and you want people to be able to follow your progress (in case they're curious or perhaps want to help out).

Maybe you decide it needs more work, so you hack on it some more:

$ vim novacc/endpoint/api.py
<hack> <hack>
$ bzr commit -m 'Try multiple locales while sorting URL arguments to avoid breaking clients that are not careful to do this. This should be considered a temporary fix.'

Since you've already pushed this branch to Launchpad once before, bzr knows to push it to the same place without more hand holding:

$ bzr push

At this point, you want to land this branch into a target branch - typically the trunk branch, but also potentially a long-running feature branch. This can happen in a number of different ways, depending on the project. At Rackspace, the goal is to follow the Patch Queue Manager approach, but it is good to understand the whole system.

If anyone is allowed to push to the trunk

If the project is such that it's ok for every project member to just push this to the trunk, you go into the relevant target branch, in this case the trunk:

$ cd ../novacc

...make sure it's up-to-date:

$ bzr pull

..and merge in the changes from your branch:

$ bzr merge ../lp765432
$ bzr commit -m "Merge fix for bug #765432"
$ bzr push lp:novacc

..and that's it.

If only approved code is allowed to be pushed (honour system)

Usually, there will be a more formal review process. For this, Launchpad offers a concept called Merge Proposals:

On the branch page, you will see a "Propose for Merging" link. Clicking this will create a Merge Proposal for your branch, by default targetted to the development focus of the project. You can add a note about the proposal, and optionally you can add a commit message to be used for when this proposal has landed.

The Merge Proposal is where all things code-review related happen. The code review process is a conversation that can happen over email or through the web interface. Developers can vote on the proposal (approve, deny, etc) and additionally the proposal itself has statuses (Approved, Rejected, Work In Progress). When a Merge Proposal changes status is a project policy decision.

todo* Add text about resubmitting proposals, changing status from Needs Review to Work in Progress to Needs Review

If it's rejected, you hack on it some more, and file a new merge proposal. If it's approved, either you or a designated "merge captain" can go ahead and do what's outlined in the "If anyone is allowed to push to the trunk" section.

If the trunk is guarded by a Patch Queue Manager

The process here is the exact same as the only-approved-code approach above, but instead of having developers do the merge themselves or having a designated merge captain do it, you can use an automated system such as Tarmac or another Path Queue . In the case of Tarmac, a Launchpad user is created on Launchpad for this purpose. This user owns the branch that is designated as the trunk. This way, noone can commit directly to the trunk. Tarmac will at intervals scan for approved merge proposals (see "If only approved code is allowed to be pushed (honour system)" section) and automatically merge each of them, run the unit tests, and push them to the trunk.

LifeWithBzrAndLaunchpad