Introduction
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.
Note
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.
Configuration
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
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
.
Note
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:
- 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.
Note
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.
https://code.launchpad.net/emacs.
Note
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:
Configure your preferred email client using the Configuration
dialog.
Define some branch settings in the trunk branch. Switch to
that branch, select 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 from the toolbar.
The original master location will be shown.
Warning
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.
Note
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:
- 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,
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:
- Select 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).
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:
- Switch to the repository view.
- Select
- Enter trunk as the source and work as the destination.
- 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:
- Select .
- Select the branch you wish to work on.
- Press OK and close the Switch dialog.
The page title will switch to work -> xxx [emacs] where
xxx is the branch name you entered.
Note
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
https://help.launchpad.net/Code/Imports.
If you wish to use Launchpad for commercial development, see
https://answers.launchpad.net/launchpad/+faq/208.
Bazaar Explorer - Version Control for Human Beings
Home