Bazaar Explorer logo Bazaar Explorer - Version Control for Human Beings

Contributing to Free Software Projects Made Easy


This tutorial explains how to contribute to free software (open source) projects using Bazaar Explorer. Even if you intend using the bzr command line tool most of the time, you may find it useful using Bazaar Explorer to get your local repository configured and to walk though the change process the first time. The bzr commands to use are displayed as you go. The project used in the examples given is GNU Emacs, bu the same process can be used for a huge number of other projects.

For convenience, the Launchpad mirror branches and merge proposal system are used. Almost any project can leverage the tools shown without needing to explicitly switch to Bazaar and Launchpad. Details on how projects can hook into Launchpad and encourage casual contributors using Bazaar Explorer are given at the end of this document.


For GNU projects, you can use the GNU Savannah hosting service directly if you prefer it instead. To do this, simply enter the URLs in place of the Launchpad ones when applicable.


If you haven’t already, install:

  • Bazaar 2.0.0 or later
  • QBzr 0.17 or later
  • Bazaar Explorer 0.10.0 or later.


These tools run on most recently released operating systems including Ubuntu 8.10 or later, OS X 10.5 or later and Windows 2000 or later. If you have any difficulty installing them, contact us on the Bazaar mailing list ( or on IRC (#bzr on freenode).

If you don’t have a Launchpad login, register and import your SSH key now.


Start Bazaar Explorer. The welcome page will be shown.


Select Configuration to configure Bazaar. Enter your name and email address. You can also configure a preferred text editor. If not set, several environment variables are checked (BZR_EDITOR, VISUAL, EDITOR) before falling back to a desktop-specific default.


Close the dialog. Select Preferences to personalize Bazaar Explorer. Select the expanded toolbar.


Close the dialog. Register your Launchpad login. To do this, Select Advanced on the toolbar, select launchpad-login as the command and enter your login-id into the relevant field. Select OK and close the dialog.

You are now ready to begin development.

Fetching the source code

On the Welcome page, select Get project source from elsewhere. Select Branch. Enter lp:emacs as the source URL and a sensible destination directory, e.g. Projects/emacs in your home directory.


Click OK. You will now be asked if you wish to create a shared repository. Click Yes. A dialog will be presented allowing you to configure the shared repository.


Accept the defaults by clicking OK. Close the Initialize dialog. The Branch dialog will be presented once more. Adjust the destination directory to trunk within the repository directory, e.g. Projects/emacs/trunk.


Click OK. Bazaar will now download the complete history of the Emacs trunk locally. This will take a while so grab a suitable beverage and read ahead while you’re waiting.

When the download completes, Bazaar Explorer will open a new page with a title of trunk [emacs]. Close the Branch dialog.


Open the locally created emacs repository and view the current list of branches. To do this, select File ‣ Open and enter Projects/emacs or whatever directory for the repository you previously entered. Click on trunk to view its recent history.


Bookmark this location (repository page) by selecting Bookmarks ‣ Bookmark this location.


The next time you start Bazaar Explorer, the Welcome page will show your list of bookmarks. You can open this page quickly by simply double clicking on the bookmark we just added.

You are now ready to begin making changes.

The basic procedures

Preparing a change

When using a distributed VCS, the recommended way of working is to make separate changes in separate feature branches, rather than making changes directly in trunk. The benefits of this approach will become evident below.

To create a feature branch, select the trunk branch in the repository view, select the Branch button and enter a feature branch name, e.g. better-readme.


This may take a few seconds because a completely new working tree is being created. When it completes, close the Branch dialog and a page for the new branch will be opened.


Fire up your editor by selecting the README file in the working tree browser and selecting the Edit button. Change the file. Switch back to Bazaar Explorer and select the Refresh action in the toolbar (or press F5). Your change should be shown in the status report.


If you wish to browse the actual change, select the Diff action (or press F3).


Commit the change locally by selecting the Commit action (or by pressing F4). Enter a commit message and select OK.


You have now saved your changes to the local repository. If you wish, you can make additional changes and commit them locally by repeating the Edit and Commit steps above.

Proposing a change

When an overall change is ready for sharing with others, there are multiple ways forward depending on your privileges and preferred review policies. These include:

  1. Push the feature branch to a central location and ask other developers to review it.
  2. Send the changes to a mailing list for discussion.
  3. Merge the change into the master branch if you have the necessary permission to do so.

This section explains the first option. The other options are explained in the next two sections.

To push to a central location, select Push on the toolbar.


The Push dialog knows the preferred way to publish to selected hosting sites (including Launchpad), so it can suggest a sensible location if you’re yet to specify one. Patches or information on what it ought to suggest for additional sites will be warmly accepted.

Enter a location or change the suggested one if required.


Select OK. Pushing your feature branch to Launchpad should generally be pretty quick as only the new revisions are sent. When the transfer completes, close the Push dialog. An indicator should now appear in Explorer’s status bar (bottom right hand corner) telling you that the branch is known on a hosting site.


Click the indicator to see your pushed branch in your web browser.


To propose a merge, click on the Propose for merging link (half way down the page). Enter a comment explaining why this change is a good idea and select the Propose Change button at the bottom of the page.


Your change is now in the review queue on Launchpad. The review queue and list of branches can on found on the main Branches page for a project in Launchpad, e.g.



It’s a good idea for your community to subscribe its developer mailing list to Launchpad’s trunk mirror. Merge proposals will then be automatically emailed to the list while remaining browsable online. See the end of this document for details on how to do this.

Emailing changes

You can email your proposed changes directly to your developer list by attaching a merge directive. For this to work smoothly, some one-time configuration is required:

  1. Configure your preferred email client using the Configuration dialog.

  2. Define some branch settings in the trunk branch. Switch to that branch, select Settings ‣ Configure ‣ Branch Configuration and the branch.conf file will be opened in your text editor.

    Add public_location and child_submit_to so they match the parent location, e.g.:

    parent_location = bzr+ssh://
    public_location = bzr+ssh://
    child_submit_to = bzr+ssh://

    Once this is done, save the changes.

To begin the emailing process, select Send in the toolbar. Enter the list address and message (subject line).

(TO DO: add Send dialog image)

Click OK and your email client will be launched with the address, subject line and attachment in place. The attachment would include a “patch preview” (diff) together with some binary encoded data recording metadata a plain patch can’t (e.g. renames). Explain why this change is a good idea in the message body and fire off the email.

Accepting a change

If you have permission to land changes onto the trunk branch, here’s the recommended way to do it. Firstly, configure your local trunk so that it is bound to the remote master. This only needs to be done once. To do this, select Work ‣ Bind Branch from the toolbar. The original master location will be shown.


If your project is only mirrored on Launchpad (like GNU Emacs is), be sure to bind to the real master branch here.


Adjust the bind location if necessary, select OK and close the dialog. The icon will now change in the page title to show that this is a bound branch, not a plain one.


Now merge the change. Select Merge on the toolbar. Enter the local path of the feature branch or the remote URL of the branch you wish to merge.


Select OK and close the Merge dialog. The status report will show the overall effect of the merge.


Resolve any conflicts encountered (none in the example above). You can do this by clicking on the links listed under Conflicts one at a time and using your editor. When addressed, click on the Conflicts icon (next to the title) to launch the Conflicts dialog and select Auto-resolve. Alternatively, skip using your editor and launch the Conflicts dialog immediately. Use your configured merge tool to resolve each conflict.

When all conflicts are resolved, browse the overall differences to confirm they look good. If you wish, select the Log action to see the steps taken to put together the change. When you’re ready, select Commit and enter a good message. Keep in mind that most users will see just the mainline commit messages initially in the Log dialog (and default command line log display) so enter a message than stands alone, e.g. “Better README”, not just “merge”. The change is now committed both remotely and locally.

Review feedback

In many cases, other developers will have changes they want made before your change will be approved. When you receive this feedback, open the relevant feature branch, make the changes, commit them and push them. Your remote branch is now ready for re-review. If you pushed to Launchpad and entered a merge proposal, open it and add a comment to that effect.


This illustrates why feature branches are the preferred development model by users of distributed VCS tools. While this review process is ongoing, you can be making other changes in other feature branches.

Branch management

After your change has been merged into the master branch, you can delete your feature branch. If you wish, simply delete the feature branch directory using your file manager or shell commands. Alternatively, refresh your trunk with the latest changes in the master branch by using the Pull action on the toolbar. Use Log to confirm your changes are there. If you want to double-check, open the repository view, click on the feature branch and select the Local changes tab. If your feature branch has uncommitted changes and local revisions not in trunk, they will be displayed.

If all is good, select the Manage action in the repository view to launch your file manager. Delete the feature branch. For small projects, it’s often fine to leave obsolete feature branches hanging around for a while and to clean them up once a week say.

Tips and Tricks

Congratulations - you now know the basic processes used to contribute to a free software project using Bazaar Explorer. This section explains some optimizations you may want to consider once you’re comfortable with the steps explained so far.

Backing up your feature branch changes

One of the things users of central VCS tools like CVS and Subversion find appealing is that their changes are backed-up to a central location each time they commit. There are several ways of achieving this in Bazaar:

  1. Bind your local feature branch to the pushed location.
  2. Push after each commit by hand.
  3. Use the automirror plugin to automatically do this push for you.

In the case of feature branches, you’ll often be the only person committing to the push location so option 3 might be a better choice (slightly faster) than the others.

Maintaining a quick-fixes branch

As an optimization, some users like to keep a quick-fixes branch in their local repository for minor changes, e.g. one line fixes, improving comments and small documentation improvements. This cuts out the need to create a new feature branch every time. Before making a change in this branch, refresh it from your local trunk by using Pull. Using a single branch like this reduces the parallel development of changes but that’s a non-issue for minor, uncontroversial changes.

Maintaining a review branch

In a similar fashion, senior developers on a project often have a review branch in their local repository. This branch is not used for making changes - it’s kept as a scratch area for reviewing changes others have proposed.

To use a review branch:

  1. Select Work ‣ Revert Working Tree to clear out the last change reviewed.
  2. Refresh from your local trunk using Pull.
  3. Grab the proposed change using Merge.
  4. Use Diff and Log to inspect the changes and collect your thoughts on whether the change is ready to land or not.

If the change in fine and it’s your responsibility to land it, follow the normal procedure (e.g. merge into trunk from the original location, tweak if required and commit).

Using a shared tree

For projects with a large number of files or a large number of build artifacts (e.g. .o or .class files), building a separate working tree for every change can be sub-optimal. In these cases, it’s often better to have a shared working tree that is re-used for multiple branches. To do this, create a (lightweight) checkout. Here’s the recommended way:

  1. Switch to the repository view.
  2. Select Start ‣ Checkout
  3. Enter trunk as the source and work as the destination.
  4. Press OK and close the dialog. A new page will be opened with a title of work -> trunk [emacs].

You now have a working tree that can easily be shared across multiple branches.

To switch the checkout to a different branch:

  1. Select Work ‣ Switch Checkout.
  2. Select the branch you wish to work on.
  3. Press OK and close the Switch dialog. The page title will switch to work -> xxx [emacs] where xxx is the branch name you entered.


Git fans/refugees use the shared tree model commonly as Git implicitly works this way. Bazaar is arguably not yet as tuned as Git is for working this way. On the other hand, Bazaar’s approach lets you have multiple working trees per repository, e.g. one for trunk branch development and one for stable branch fixes. We leave it to you to pick the best number (0, 1, 2 or more).

Pipelines, looms and more

For documentation on popular Bazaar plugins, see the Plugins Guide. Two particularly useful ones are outlined below. After installing these plugins, all of the special commands added are available via the Advanced action on the toolbar.

In many cases, it’s a good idea to develop a larger change by splitting it into smaller pieces. For example, a new feature may require a new subroutine in a lower level library as well as new code to use that new subroutine. To simplify reviews, it can be useful to build changes like these as a pipeline of branches. A single branch is a pipeline of length one so get started by developing the lower level change in a shared tree switched to a new feature branch. Then add a pipe when you want to begin on the next branch in the sequence. See the pipeline plugin for more details.

At other times, you may want to track an upstream project and maintain a stack of patches above it. In this case, the pipeline plugin could be used but the loom plugin is a better choice.

In summary, there are many ways to use Bazaar effectively. As a rule though, start with the generally recommended way - feature branches in a local shared repository - and experiment with the advanced options (shared trees, pipelines, looms) only when you’re confident to do so.

Using Launchpad and Bazaar to encourage casual contributors

Among other things, Launchpad has been designed from the beginning to be a code supermarket and federated bug tracker. In other words, it was designed as a one-stop shop for casual contributors to find interesting code and raise bugs for all packages in Ubuntu, regardless of what VCS system and bug tracker is used by upstream projects.

Here are the steps a project can take to leverage Launchpad, without changing its upstream VCS tool and code review process:

  • Register the project (if not already done).
  • Ask for a code import of its trunk (if not already configured).
  • Register a psuedo-user with the project’s mailing list as the user’s email address.
  • Subscribe that psuedo-user to code review changes on the imported trunk.

That’s it! After that, casual contributors can browse your code on Launchpad and use the tools above to propose changes. For more details, see the Launchpad help, particularly

If you wish to use Launchpad for commercial development, see


We hope you’ve found this tutorial useful. If you have ideas on how it could be improved, you can fetch it from lp:bzr-explorer-website and propose a change using the procedures given above. Alternatively, enter a bug in our bug tracker. Enjoy!