The importance of bzr whoami

One of the really important things that lots of people forget is to start off with is setting your name is Bazaar. This can be done really easily by doing bzr whoami "Your Name <email@example.com>" It's important that you set this properly, or your revisions aren't going to get your name on them. The email address you set here also needs to be an email that Launchpad knows about (a confirmed address). This way, you get the karma for the revisions, and revision listings in a branch page will link back to your profile.

Set a Development Focus

Because we're talking about a distributed version control system, there are going to be many branches in your project. It's important to point people glancing at your project to the "trunk" of your project, where all the new fun development it. Once you've pushed up your first branch, it's good to set it as the development focus. Now, new contributors will know where to branch from when they want to, well, contribute.

Setting a development focus also tells Launchpad itself what branch is your main branch. For instance, because I have the development focus of Entertainer to lp:~entertainer-releases/entertainer/trunk, every time I do a bzr branch lp:entertainer Launchpad knows to give me the correct branch. It's an alias that can save you a lot of time. I often find myself doing bzr branch lp:randomproject just to get the most up to date source.

A quick note about series branches. When you decide to release your software (because you're releasing software often, right?), you'll want to keep a branch of that version. That's what's called a series branch. It'll have point release milestones attached, and when you release those point releases, they'll come out of this branch. The development focus is a glorified series branch. So, in effect, if you create a series branch called myproject-1.1 in the myproject project, you can use bzr branch lp:myproject/myproject-1.1 to get your myproject-1.1 series branch.

Since branches are owned by people, you might want to consider creating a team that owns your development focus, and adding people to that team. This keeps your project moving when you go on vacation for two months. It's just a good idea.

Workflow decisions

Now, you need to decide what your workflow is like. Some projects only have one person working on them. If that's your project, then all you need is one branch, commit, push to Launchpad. That's relatively simple. I do this with a few personal projects.

If your project has more than one person, then you've got to make other arrangements. What I suggest is the concept of feature branches. Create a branch specifically for a feature or a bugfix, hack it all together, and merge it into your trunk. This is the optimal solution, and, as far as I'm concerned, the only solution.

It's a good idea to see my former post on good Launchpad/Bazaar settings This will take the hard work out of pushing, especially with feature branches. What I usually do is keep a mirror of the development focus branch on my system (with a cron job to update it at regular intervals). When I start a new branch, I branch from that mirror, and start hacking. I try to push at normal intervals, but sometimes I just space that.

Merge Proposals and Code Reviews

So now you're creating feature branches, because, well, that's the workflow you've chosen. You've written your tests (because you tested first, right?), your feature is ready to land (or so you think). At this point, you should propose it for merging into your development focus branch. No matter how your project handles reviews, it's good that someone at least blesses the revisions that are to proposed to land in trunk.

So your branch goes through the review process, comments are made, and eventually, all required reviewers approve of your changes. Now it's time to actually get your branch landed. Someone in the team that owns your development focus will need to merge your branch into their local copy of the "trunk" and then push it up. Once that's happened, Launchpad will mark the merge proposal and your feature branch is also marked as merge. Go hack on another branch!

For Reviewers

So there are a few different pages that help to know about if you're a reviewer for a project. The first is the +activereviews page. If I navigate over to the Entertainer active reviews page you'll see that I have some landing work to do. This also applies to people. If I navigate to my own active reviews page you can see all the branches that I have submitted for review.

What if, however, I want to see all the reviews I've done for someone else's branch, and what the status of those branches is. Maybe I set my review vote to "Needs Fixing" and now I need to see if that fixing has occurred. That's when you'll want to check out your +requestedreviews page (as of this writing, currently only available in beta, due out in a week). If we go take a look at mine, you'll see that I have some work to do.

Bazaar branch formats

As Bazaar features get implemented, new formats become a result (so as not to risk breaking old, tried and true formats). As of Bazaar 1.6, a feature called "stacking" was introduced, that allowed bzr branches to only have the history specific to that branch, and just keep a reference to the trunk branch. This is great if you have LOTS of history for your project, and pushing seems to take forever. If you upgrade your branch to format 1.6 by doing bzr upgrade --format=1.6 you'll now be able to push stacked branches.

If you're using the Bazaar PPA (and you really should be using it), you'll have a 1.9 format available. It's faster, supports stacking, and is awesome all around. It's not the default format, so you'll have to either create your branch with bzr init --format=1.9 or bzr upgrade --format=1.9.

Import branches

Distributed version control drastically reduces the barrier to entry for hacking on a project. With a VCS like CVS or Subversion, the project usually works as a meritocracy, and so you have to "prove yourself" before you get access. What if a project you really want to hack on won't give you commit access to their SVN/CVS repo? Create a project in lp, and import the the SVN or CVS branch into a bazaar branch. Then all you need do is branch from that branch, and hack on. When you're done, you diff between the current import and your branch, and send that in as a patch to the project itself. The difference is that you have a versioned copy of the making of that patch, instead of having a single checkout.

Comments and suggestions are welcome. I'll do my best to keep this post up to date with new things, and once it's baked, I'll publish to a wiki somewhere.