Working with bazaar

Before you start

Before you do anything with bzr, remember to tell bzr who you are:

• bzr whoami "Your Full Name <your.full@email.com>"
• bzr lp-login your-launchpad-username

Basic project layout

For most projects, there will be one common source code branch that new releases will be taken from. In our case this is the dhis-academy trunk [1], which I will periodically be merging changes to from the dhis2 trunk [2].

In your projects you will be working on extending this code base with a new feature, and that work you will be doing on what can be called a feature branch. Once you have completed the new feature on your branch, this branch will be merged back into the common branch and released with a new version.

[1] https://code.launchpad.net/~dhis-academy/dhis2-academy/trunk
[2] https://code.launchpad.net/~dhis2-devs-core/dhis2/trunk

Suggested workflow

Creating project branch

1. bzr co lp:dhis2-academy
2. bzr branch dhis2-academy <your-branch-name>
3. cd <your-branch-name>
4. bzr push --use-existing <your-branch-url>
5. bzr bind <your-branch-url>

This last step makes the branch a checkout, so commits will now go directly to launchpad instead of just locally. After this you will have two checked out branch folders locally, one for each branch on launchpad:

• dhis2-academy
• <your-branch-name>

Working on your branch

When you use check out and not branch, you will be working on the branch just a you would with an old-style centralized vcs like subversion:

• cd <your-branch-name>
• bzr up - Get changes from other people working on your branch
• bzr ci - Commit my local changes to the branch on launchpad

Updating your branch with changes in trunk

Sometimes it will be necessary to update your branch with changes from trunk, if someone else have done changes to the services you depend on or something like that. 

In order to do this:

• make sure you don't have any uncommited changes in your local branch folder, and that it is uptodate.
• cd dhis2-academy
• bzr up
  • updating you local version of trunk with changes on launchpad
• cd ../<your-branch-name>
• bzr merge ../dhis2-academy .
  • merge trunk changes into your branch
• bzr ci

Merging your feature back into trunk

When you are finished and satisfied with your new feature, it is time to get it back into trunk.

• Check that your local copy is uptodate and don't have local changes
  • cd <your-branch-name>
  • bzr up
  • bzr st
• cd ../dhis2-academy
• Make sure trunk is uptodate and don't have local changes
  • bzr up
  • bzr st
• bzr merge ../<your-branch-name> .
• bzr ci

Best practices and pitfalls

The suggested workflow above, should be all you need. But you do of course have to take care of a lot more, like

• resolving any conflicts that might arise
• test that everything is compiling fine
• test that all tests are passing
• check that the app starts up as it should

Basically, when working in a distributed fashion, it is always your responsibility to make sure you don't create problems for anyone else.

If you have the need for more freedom, you should always just create your own private branch, locally or even on launchpad. One way is to have two local copies of the branch you are working on, one where you do your own work and one clean version:

• bzr branch <your-branch-name> <my-working-branch>

With this working-branch you can commit locally as much as you like, and when you are ready to share with the others in the group you do rougly the same as above:

• cd <your-branch-name>
• bzr merge ../<my-working-branch> .
• bzr ci

I trust by now you understand that you need to do things like bzr up and bzr st at appropriate points..

The problem with bzr push

Why don't I suggest using bzr branch like the launchpad sites seem to suggest?

There is nothing wrong with working in a truly distributed fashion, branching instead of checking out. But it is important to understand that this quite easily creates problems with  the revision history if used the wrong way.

When you branch, the way you get your changes back to a shared "parent" branch on launchpad is to push it. Basically part of the the workflow could be like this:

• bzr branch lp:dhis2-academy
• cd dhis2-academy
• bzr push <your-branch-url>
• do local changes
• bzr ci
  • local commit, not on launchpad
• bzr merge <your-branch-url>
  • Get changes from your other project memebers 
• bzr push <your-branch-url>
  • Push your changes to your project branch

What would happen here is that the version history on the team branch would have all your local commits, while the commits of your co-workers would be swallowed into one by the merge. So if you were to work like this towards trunk, you could easily remove the version history of what everyone else have commited to trunk, replacing it with your own local commit history.

If you choose this way of working, it is therefore very important that you always have a clean branch from launchpad that you merge your changes into, and push from this branch rather than the one you work locally on. And personally I prefer this branch to be a checkout instead, just to be on the safe side.