Revision as of 15:17, 16 July 2010

<<TableOfContents()>>

Life with bzr and Launchad

BzrPerfectWorkflow contains a high-level overview of what we're trying to achieve. Alternatively, GitBzrInstructions contains a tutorial on how to use launchpad with git.

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.

If as the result of conversation or review the branch author decides more work is needed and he will resubmit later, he can simply set the status on the Merge Proposal to "Work In Progress" which will remove it from the review queues. When he's ready for review again, he can either set the status back to "Needs Review" - or he can click the "resubmit proposal" link, which will submit a brand new proposal which contains and references the original one. This can be useful if enough work has been done that original review votes should be cast again.

Once the Merge Proposal is 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 Patch Queue Manager system such as Tarmac. In this case, a special 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 if the trunk is clean. If there is a problem with the merge, the Patch Queue Manager will report the problem as a comment on the merge proposal and reset the merge proposal status to Work In Progress.

Working with Blueprints

Blueprints offer a forum for listing and planning specifications for work to be done. Whereas one could think of these as bugs with a "Feature Request" priority, there is actually a more fundamental difference. A bug is a description of a problem, and a blueprint is a description of a solution. It would be perfectly legitimate, given the scope of a particular problem, to file a bug on a problem and then to write up a blueprint describing the approach to solving the problem. For most bugs this would be a rather large waste of time, but is merely pointed out to underscore the difference in purpose.

The Blueprint system itself is quite simple, and the only thing required to create a blueprint is a title and a description of the blueprint. It is expected that longer-form official writeups of the approach would go on a wiki page, and accordingly the blueprint has a field for specifying where the writeup can be found. The intent here is that if you write a proper description of the work in the wiki, then once you are done with it you will be left with some form of documentation describing a particular feature.

Blueprints, like bugs, can be targeted towards different release series and different milestones, so that at any point it's simple to see what the status of intended work is.

Blueprints can also be used as the basis for planning in-person meetings. Launchpad contains a facility to register meetings, and blueprints can be targeted to available meetings as an element of agenda.

Adding a Blueprint

Adding a blueprint is simply a matter of going to the project's blueprints page, such as

https://blueprints.launchpad.net/novacc 

and clicking on "Register a Blueprint"

Assigning a Blueprint

Blueprints carry metadata about who wrote the spec, who approved the spec and who is implementing the spec. If there is a blueprint that you are going to be working on, simply change the assingee to yourself and off you go.

Updating Status

Blueprints carry a status field about the relative status of the work. Although not strictly necessary, updating this status removes the need to constantly answer questions from your manager of "what's the status on project X"

Linking a branch

Once there is code related to a blueprint, it's a good idea to link that branch to the blueprint, so that someone looking at the blueprint can see that there is a branch in progress.

Resources and Gotchas

The folks at Canonical have a couple of pages up that may be useful for folks migrating

http://doc.bazaar.canonical.com/migration/en/survival/bzr-for-git-users.html

http://doc.bazaar.canonical.com/migration/en/survival/bzr-for-hg-users.html

Adding Files

For folks coming from git, the bzr add command may be a source of some confusion and consternation. In bzr, all changes made to any file in the tree are automatically included in bzr commit, so one does not add files to the index before committing. In bzr, the add command is used to add newly added files to the branch. It is therefore important to remember to run bzr add after creating a new file or directory, but really no other times.

Rebasing

Another gotcha for folks coming from git will be workflow differences around rebasing. Simply put, while rebasing can be done in bzr, it is not a part of the standard workflow and should be avoided in most cases.