Bazaar Tutorial

This tutorial will show you how to checkout, modify, commit, and propose a merge for the Ubuntu-ZA web site. While these instructions are specific about the Ubuntu-ZA site, they will work for almost any other project on Launchpad.

Set up Launchpad

New to Launchpad?

If you don't have an account on Launchpad.net, go to https://launchpad.net/+login to create one and log in.

Generate and Upload SSH Public Key

Once you're logged in, you'll need to make sure you have your SSH public key uploaded to your account.

Generate SSH Keypair

SSH uses keypairs, a dual set of keys used to authenticate you against remote services. This keypair consists of a private key and a public key. To generate a keypair from your terminal, type in:

$ ssh-keygen -t rsa

This will create an SSH keypair using the RSA algorithm. Now you need to upload your public key to Launchpad. Display your public key on the terminal by typing in the following:

$ cat ~/.ssh/id_rsa.pub

Upload SSH Public Key

Once you've done this, go to your Launchpad user page. On your user page there is a section titled, SSH keys. Click on the little yellow icon next to it to edit your SSH keys. On the next page, scroll down to the bottom and copy and paste your SSH public key into the text box at the bottom, and click the button to import it.

Set up Bazaar

Identify yourself

You need to configure Bazaar with your name and email address so that your commits can be identified. You should use your email address which is registered on Launchpad:

$ bzr whoami "John Doe <john.doe@example.com>"

Log in to Launchpad

Then you need to log into Launchpad from Bazaar. Type in the login command, followed by your Launchpad username:

$ bzr launchpad-login john-doe

Set up Projects Environment

Next you need to set up your directory structure to support using Bazaar and Launchpad.

Create a local Projects directory:

$ mkdir ~/Projects

Create a local bzr shared repository:

$ cd ~/Projects
$ bzr init-repo ubuntu-za

Checkout Main Branch

Now you need to checkout the Ubuntu-ZA site. This means that you're going to tell Bazaar to create a local version of the branch at lp:ubuntu-za. I like to call it trunk because it's connected directly with the primary branch on Launchpad.

Checkout the Ubuntu-ZA site:

$ cd ubuntu-za
$ bzr co lp:ubuntu-za trunk

This will create a new directory called trunk in ~/Projects/ubuntu-za.

Branching, Pushing, Proposing and Merging

In order to work on the project you need to create branches to do the work in, then push your local branches up to Launchpad, and then propose a merge, and finally merge your changes in to the main branch.

Create a Branch

To create a new branch, make sure you're in your shared repository directory, and use the branch command:

$ bzr branch trunk new-contact-page
$ cd new-contact-page

Make your edits. Add any new files you have created:

$ vim pages/contact.rst
$ bzr add
adding pages/contact.rst

Commit your edits (with a commit message explaining your changes), to save them to your local branch:

$ bzr commit -m "Add a new contact page"
Committing to: ~/Projects/ubuntu-za/new-contact-page/
added pages/contact.rst
Committed revision 8.

Push a Branch

In order to have your branch visible to the other developers, and in order to propose a merge, you need to push it up to Launchpad. This will create a remote branch on Launchpad, identical to your local branch.

Use the push command:

$ bzr push lp:~john-doe/ubuntu-za/new-contact-page
Using default stacking branch /+branch-id/16860046 at chroot-65050896:///~john-doe/ubuntu-za/
Created new stacked branch referring to /+branch-id/16860046.

Each time you push up a branch, it should follow the same pattern:

lp: ~<Launchpad username> / <project name> / <branch name>
lp:
This is the Launchpad "protocol"
~<Launchpad username>
This is your username on Launchpad, with a ~ prefixed, and tells Launchpad to associate this branch with you
<project name>
The project this branch is associated with; in our case, "ubuntu-za"
<branch name>
This is the name of your remote branch; anything alphanumeric

Propose a Merge

Go to your branch page on Launchpad. There are two ways to get to your branch page: either via your code page, or via the ubuntu-za project code page.

To get to your code page, go to https://code.launchpad.net/~<Launchpad username>. The ubuntu-za project code page is just as easy to get to: https://code.launchpad.net/ubuntu-za.

Next, click on your branch in the list. Then just click on the "Propose Merge" link and propose a merge.

Merging

Note: Merging into trunk is done by the core developers. If you are not a core developer, you won't be able to commit to trunk.

In your local trunk directory, run the merge command:

$ bzr merge lp:~john-doe/ubuntu-za/new-contact-page
+N  pages/contact.rst
All changes applied successfully.

This merges the changes from that remote branch into your local files. Now you need to commit those changes into the repository, which will send them up to the main branch:

$ bzr commit -m "Add a new contact page" --author="John Doe <john.doe@example.com>"

Once again, you need to specify a commit message (usually just a copy of the merge proposal message or the last commit message in the remote branch), and the author of the commit. This author flag gives credit to the original author of the changes, even if they do not have permission to write to the main repository. Give credit where credit is due.

Updating

Lastly, everyone else who has a copy of trunk will need to update their copy. Just run the update command:

$ bzr update
+N  pages/contact.rst
Updated to revision 8 of branch bzr+ssh://bazaar.launchpad.net/+branch/ubuntu-za

And you're done.