This document explains a few of the version controlled development techniques which are used by the Mira developers. These are just examples which are intended to give you some ideas on improving your own development methods and are in no way all of the techniques that are available. The beauty of Bazaar is that it caters for all kinds of methodologies, so if the techniques shown on this page do not suit you then the Bazaar User Guide might be a better place to look.

This document assumes that you have already configured Bazaar appropriately to access the Mira repository as a developer (i.e. with full read/write privileges).

Creating a local branch from a repository allows you to work on the code at your leisure. You can commit your incremental changes locally and, when your code is mature enough to be uploaded, to push those changes and revisions to the shared repository using a single command.

For the purpose of simplicity, the examples in this document will use a branch created in a 'Projects' directory under the home directory on a Linux system (so that the root directory of the branch will be ~/Projects/mira). To branch from the repository, run the following command from a terminal emulator:

mkdir ~/Projects/
bzr branch lp:mira/trunk ~/Projects/mira/

This will create a local branch of the trunk series (which is under active development) of the lp:mira branch. The source code will be branched into a local directory named mira (which is located under ~/Projects).

Simple, isn't it?

You can now use this branch to develop the source code. Let's assume that you have edited a few files and also added two new files. Because of the way that Bazaar works, it will see that the edited files have changed but it will not recognise the addition of those two new files until you tell it to. So, let's do that. First, make sure that you are in the top level of the branch (i.e. the original mira directory that we created). If you are not, make sure to change into it:

cd ~/Projects/mira/

Now, run the following command to add your two new code files to Bazaar's change tracking system in the local branch:

bzr add *

Great! Bazaar is now aware that you have edited some files and also added two new files to the branch. Just to be sure, it is always worth checking what changes have been made to the branch since the last revision by running:

bzr diff

If everything looks good and all the expected changes are shown, you are now ready to commit your changes to the local repository - this will store your modifications in Bazaar's internal record keeping system. To do so, run the following command and add a comment (between the “quotation marks”) which is relevant to your changes:

bzr commit -m "Added support for internationalisation. (this is an example of a comment)"

You can now either continue to work on the code and make further local commits, or you can push your update to the central repository. Please make sure that your code builds before you commit it to Mira's development branch! There is little worse than buggy code being propagated to all our innocent developers. If you're sure it compiles without a problem, run the next command to send your changes to the main Mira branch:

bzr push --remember lp:mira

Voila!

If you are afraid of corrupting Mira's development branch but would still like other developers to review your code, there is a solution. Instead of pushing your changes to Mira's development branch (lp:mira), you can push your changes to a personal branch which will automatically link to the Mira project on Launchpad. Pretty cool, right?

This is quite simple to do. All you need to do is replace <yourLaunchpadUsername> in the command below with - you guessed it - your Launchpad username, and <branchName> with a name that you think would be fit for this new branch (e.g. 'i18n-support'):

bzr push lp:~<yourLaunchpadUsername>/mira/<branchName>

That's all there is to it! The Mira Core Development Team can then review your code and decide whether or not to merge your changes into the development branch.

It is also possible to develop features in separate branches so that you can edit the source code without changing the original local branch.

Let's assume you want to build a new feature - a GUI feature, perhaps. Let's be creative and call it gui-feature, shall we? Why don't you create a new branch for this:

cd ~/Projects/
bzr branch mira gui-feature

There is now a new branch called gui-feature located under ~/Projects.

Let's skip ahead a few hours: you have been working on gui-feature and have made sure that Bazaar has been tracking your changes (with regular commits to the gui-feature branch). You have compiled your code and it works beautifully; it's time to upload it to the development branch. First, let's move back into the original mira branch:

cd ~/Projects/mira/

Now you can merge your code from gui-feature into the original branch:

bzr merge ../gui-feature/

Don't forget to review the changes before recording them by committing to the branch:

bzr diff
bzr ci -m "Added a stunning GUI feature which does X when Y happens"

But wait! That's not it yet, remember? To upload these changes, make sure to push them to the repository:

bzr push

Brilliant. But now you might ask: what happens if someone else commits a new revision to the repository while I'm working on gui-feature, and I need their updates to finish working on the feature?

Great question!

So you're working on a “sub-branch” (e.g. gui-feature) and someone else updates the repository with some code that you need. Remember: the local mira branch was created from lp:mira, whereas gui-feature was branched from the local mira. This means that you need to update mira and then merge the updates into gui-feature, as follows:

cd ~/Projects/mira/
bzr pull
cd ../gui-feature/
bzr merge ../mira/

As you might have guessed, the bzr pull command updates the original mira branch, and the bzr merge command then merges the updates into gui-feature.

Conflicts can arise when you are working on a branch and someone else commits to the repository with changes to some of the files which you have also edited. An example of when this might occur is when updating a “sub-branch”.

Fortunately, Bazaar has very good support for conflict flagging and resolution. For more information on how to discover and resolve conflicts, please read this tutorial: Conflict Handling

If you are fixing a bug which has been filed on our Launchpad Bugs bug tracking system, you can link your fix to the bug by committing your code as follows:

bzr commit --fixes lp:12345 -m "Fixed bug 12345 by adding a missing bracket"

All you need to do is change the 12345 to whatever the reference of the bug is - Bazaar takes care of the rest for you. It's really that easy!

Once you've checked and double-checked that your patch works (and doesn't break anything else), push your fix to the repository.

Let's say you've made some changes to the branch but are not yet ready to commit them - you'd rather the other developers reviewed them first and got back to you with their thoughts and criticisms. One way of doing this is to use Bazaar's in-built 'bundle' tool to record a list of your changes (along with relevant Bazaar metadata).

If you've made the changes within the original mira branch, run:

cd ~/Projects/mira/
bzr bundle > ../my-changes.diff

Alternatively, let's say you've been developing gui-feature and would like to export a diff of that branch compared to the original mira branch. This is also possible:

cd ~/Projects/gui-feature/
bzr bundle -r branch:../mira/ > ../gui-feature.diff

When another developer receives your bundle, they can either read it using a text editor or merge it into their own branch with the command:

bzr merge ../gui-feature.diff

For an explanation on the difference between a 'bundle' and a 'diff', see this blog post: Bazaar Bundles

This is more important for developers who aren't a member of the Mira Core Development Team and so cannot commit to Mira's repository. If you are not a Core Developer but have been working on a new feature or patch and would like it to be merged into the repository, this can be done by using Bazaar's in-built email support to send a diff of your changes to the Mira Development Mailing List.

First, you need to configure Bazaar to use the right SMTP settings to prepare your email. Open up your Bazaar configuration file (~/.bazaar/bazaar.conf in Linux, otherwise check this tutorial) and set the following variables:

smtp_server = mail.yourSMTPserver.com
smtp_username = yourSMTPusername
smtp_password = yourSMTPpassword #you can leave this blank if you would rather enter it every time
mail_client = default

The mail_client variable can be configured to use a variety of different email clients: instead of 'default' you can use 'evolution', 'thunderbird', 'claws', 'mutt' or 'kmail' (or 'mapi' on Windows) as appropriate. Please check the Bazaar manual for more information. It is also possible to use Gmail as your email client (see this tutorial).

All you need to do to send the merge request is to run the following command to prepare the email (which will attach a bundle of your last committed changes to the message) and then hit the 'Send' button from your email client:

bzr send --mail-to='mira-development@lists.sourceforge.net' lp:mira

If you would like to create an archive of a branch - whether as a backup, to send to someone else or for any other reason - you can do so with the following command:

cd ~/Projects/mira/
bzr export ../mira-archive.tar.gz

You can also create an archive of the Mira development branch with the command:

cd ~/
bzr export mira-archive.tar.gz lp:mira