The Bazaar or "An Explanation of Bazaar for the (Almost) Typical Contributor"

Q: What is Bazaar?

From the [http://bazaar-vcs.org/ official Bazaar site]:

Bazaar is a distributed version control system available under the GPL that aids open source development and reduces barriers to participation. Our priorities are to be safe, friendly, free and fast, and to support Windows, Linux, UNIX and the Mac OS. Bazaar gives you fast, distributed revision control that "Just Works", supporting renames of files and directories smoothly. Bazaar is designed to maximise the level of community participation in your project.

Q: As a typical person who is interested in contribution, what would I use Bazaar for?

If you have ever felt the need to contribute to an Ubuntu project, you will need to learn Bazaar. On a simple level, it is the application you will use to get files from the archives for manipulation. It isn't horribly difficult, but there is a vast lack of knowledge on the subject.

Q: Aren't there already documents out there?

Yes, but not aimed at someone outside of the field of 'coding'. Bazaar has many useful features that would aid a great number of people who are developing work that doesn't fit into the traditional computer 'code'. This might include sound packagers, art packagers, documentation packagers, etc.

Q: I have heard Bazaar integrates with Launchpad, is this true?

Yes. One of the most powerful aspects of a traditional non-coder type is this integration. You can start a team, build documentation for it, register specifications and features, and a plethora of other details. All of this functionality is reflected through the central Launchpad site, with links created automatically for you.

Q: Bazaar sounds complicated, is it?

No. Getting up to speed is very easy. If you want your project to be collaborated on, it is probably a wise choice.

Prerequisites or "What the heck do I need to make Bazaar work?"

The Bzr Package

In order to get Bzr up and running, you will need to install the program itself. Use your favorite package manager in Ubuntu to install the package  bzr , or, alternatively, issue a  sudo apt-get install bzr  from the command line.

SSH Key

SSH is an tool used to provide secure transmission. The default Bazaar repository relies on it to validate all connections. This means that in order to be able to put things on the Bazaar server, you will need to have a valid ssh key located on Launchpad.

Q: How the heck do I create a public key to put on Launchpad?

Open a terminal and issue a  ssh-keygen -t rsa -C Your Name <your-email-address@wherever.com> 

• -t sets the encryption type to RSA --  man ssh-keygen  for more information.

  <your-email-address@wherever.com> should obviously be replaced with your email address surrounded by angle braces.

Once you have done this step, you will now have two files in your home account. They are located in the 'hidden' subdirectory called  .ssh . To see this directory and files inside, you can open up your file browser in your home directory. Press  <CTRL>h  to see hidden files. You should now have a folder called  .ssh  visible to open up.

A ssh 'key' consists of two parts -- a public part and a private part. The private part you keep safe and away from prying eyes. The public part is the component we will give to others -- in this case -- the portion we will publish to Launchpad. In particular, within your  ~/.ssh/  directory you will now have two new files:

1.  id_rsa  is your private key. Never give that one out.

2.  id_rsa.pub  is your public key. This is the one you will publish.

Q: Ok I have the 'keys' that ssh-keygen created, where do I put them?

Open up a browser and point it to your Launchpad account. If you do not have an account, register one. The ssh key input link for your account is located on the left:

If you click on the link, you will be given an input box to place your key into. Open up the keyfile called  id_rsa.pub  and copy / paste the contents into that box. Submit it and you are done.

Your First Trip to the Bazaar

For our example, we will use a relatively simple theme package from the Ubuntu repositories. To see the package working, add it by issuing an  sudo apt-get install blubuntu-look . Once it is installed, your system will look different, to flip back, simply remove it via  sudo apt-get remove blubuntu-look .

Let's say that we wished to tweak some of the artwork in the package. This is where Bazaar comes in, and we will demonstrate how simple it is to 'pull' -- or fetch -- the 'sources' for this package. The 'sources' for this package consist of a good number of artwork pieces, a few input files, and some other details that we won't bore you with here.

The package 'home' is located on Launchpad.net, and you could easily travel to http://www.launchpad.net and search for "blubuntu" to find it. The following link is relevant to us to get the full 'location' of the development branch: https://code.launchpad.net/~ubuntu-art-pkg/+branch/blubuntu-look/ubuntu

Your First Pull or "Pulling for fun"

We will perform the following tasks using the 'terminal'. Open up a terminal and issue  bzr checkout https://code.launchpad.net/~ubuntu-art-pkg/+branch/blubuntu-look/ubuntu my-blubuntu 

The syntax is quite simple:

1.  bzr  invokes the program.

2.  checkout  is a parameter, or mini-command, that describes what you want bzr to 'do'.

3.  https://code.launchpad.net/~ubuntu-art-pkg/+branch/blubuntu-look/ubuntu  is the full link that is obtainable from the above Launchpad search described above.

4.  my-blubuntu  is an optional parameter that tells  bzr  where you would like to create a directory to house the files.

Once the process completes, you have a full working directory that you can browse to change elements of. The explanation of all the files is beyond the scope of this document, so we will leave that for your further exploration. Before you begin to dabble too heavily in a public project, it is recommended that you talk to your team and figure out what protocols, practices, etc., that they might have in place for participation.

INCOMPLETE -- WORK IN PROGRESS