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
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
For GNU projects, you can use the GNU Savannah hosting service
directly if you prefer it instead. To do this, simply enter the
savannah.gnu.org URLs in place of the Launchpad ones when applicable.
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
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
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,
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.
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
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:
- Push the feature branch to a central location and ask
other developers to review it.
- Send the changes to a mailing list for discussion.
- 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.
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.
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:
Configure your preferred email client using the Configuration
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://bazaar.launchpad.net/~vcs-imports/emacs/trunk/
public_location = bzr+ssh://bazaar.launchpad.net/~vcs-imports/emacs/trunk/
child_submit_to = bzr+ssh://bazaar.launchpad.net/~vcs-imports/emacs/trunk/
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
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
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.
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.
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
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:
- Bind your local feature branch to the pushed location.
- Push after each commit by hand.
- 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,
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:
- Select Work ‣ Revert Working Tree to clear out
the last change reviewed.
- Refresh from your local trunk using Pull.
- Grab the proposed change using Merge.
- 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).
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
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
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
- Subscribe that psuedo-user to code review changes on the imported
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