Managing HelenOS source with Bazaar

This should help you to start using our new VCS, Bazaar. Please read this little guide carefully. Inappropriate use of Bazaar WILL make a mess in our repository. This page only documents how to use Bazaar with HelenOS. If you are confused and want to know what happens behind the scenes, read the Bazaar Theory.

Linear History

If you are doing a simple change (or several simple, unrelated changes) you might try to go for linear history. This will only work if nobody else pushed any changes to the main repository while you were doing your changes. Start by creating your private branch:

$ bzr branch bzr://bzr.helenos.org/head my_branch

This will create a branch (and working copy) under the directory my_branch. Now make some changes and commit them to your private branch:

$ cd my_branch
my_branch$ ...modify some files...
my_branch$ bzr commit -m "Fixed crash when writing zero bytes to FAT."

Now we can try and push back our changes to the main repository:

my_branch$ bzr push --remember bzr+http://jermar@bzr.helenos.org/head

In the command above please replace jermar with your username. Next time you can just use

my_branch$ bzr push

If nobody pushed any changes since the point you branched off, this will work. Otherwise it will fail. If it fails like this:

...

you have two options. Either rebase your changes to the mainline head or switch to structured history workflow.

Rebasing

Structured History

Stuctured history is good. If you are working on some feature and produce several related commits, it is better to group them to a separate branch. Also, with Bazaar it is not uncommon to have long-running branches (that are merged after weeks, months). Do not be afraid of structured history.

If your branch diverged from the mainline (i.e. somebody pushed to the main repository since you branched off), you cannot push anymore. You must merge the two branches. With merging, the order of arguments is significant. You must always merge your branch into the mainline, never the other way around! How can you do this? With bazaar you can only merge to a local repository (you need to chdir into it), you cannot merge to a remote repository.

Therefore we have to resort to a little trick. Suppose your branch my_branch diverged from the mainline. We thus create a new branch head_clone which will be a clone of the mainline:

$ bzr branch bzr://bzr.helenos.org/head head_clone

Now go to the clone repository and merge your branch into it:

$ cd head_clone
head_clone$ bzr merge ../my_branch
head_clone$ bzr commit -m "Merged FAT server improvements."

The comment for the merge changeset should summarize the changes done on that branch (or, it could just name that branch, if it was a well-known one). Now we can push from the clone to the main repository:

head_clone$ bzr push bzr+http://jermar@bzr.helenos.org/head

Finally let us sync our branch with the main repository:

head_clone$ cd ../my_branch
my_branch$ bzr pull

Again, the push might have failed if somebody else pushed since you created your head_clone. In that case probably the best idea is to try and rebase your merge commit to the new mainline head.

Conclusion

Unfortunately we have no way of enforcing the right direction of merges. So think twice before you push.