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 

   • This is your private key. Never give that one out.

2.  id_rsa.pub 

   • This is your public key. This is the one you will publish and share with people.

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.

Getting Started with Bazaar or "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

Q: I think I understand what a package is and where to get it. How do I get the package source to my computer?

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 

   • This will invoke the bzr program.

2.  checkout 

   • This is a parameter, or mini-command, that describes what you want bzr to 'do' -- in this case -- a 'checkout' that will pull all of the package source to your local computer.

3.  https://code.launchpad.net/~ubuntu-art-pkg/+branch/blubuntu-look/ubuntu 

   • This is the full link that is obtainable from the above Launchpad search described above.

4.  my-blubuntu 

   • This is an optional parameter that tells  bzr  where you would like to create a directory to house the files. If you don't provide this parameter, bzr will attempt to create the branch according to the HTML address you provided. In this case, the subdirectory it would create would be    ubuntu .

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.

Returning to the Bazaar or "Setting up shop at the Bazaar"

So you have downloaded the source code for your project. You have explored the directory and found some files that make sense and others that completely elude you. Perhaps you explored Launchpad a little bit further in an attempt to reveal some of its powerful features. All in all, you think you have a handle on what is going on with your package.

Q: How do I know that what I have on my local computer is up to date?

One important feature of bzr is its local storage of all used variables. When we first did our 'checkout', bzr did a bit of behind-the-scenes work to make things easier for you. For example, if we wanted to make certain that we had downloaded the most recent update, we now need enter into the  ~/my-blubuntu  directory we created and execute a simple  bzr up  command to update the files. No more URL needed! It is automatically remembered by bzr.

Q: I have a file called 'foobar.png' that I would like to add to the package, how do I do this?

Let's for a moment assume that you have created a PNG image for our example package blubuntu -- a wallpaper. We will assume that you have a wallpaper PNG in a file called  foobar.png .

Following the basic outline of structure that the package has, simply copy the file into an appropriate area. For our example, let's create a subdirectory of  ~/my-blubuntu  called  extra-wallpapers  and copy our  foobar.png  file into it.

Q: Easy. Now how do I tell bzr that I want it to see added files?

To accomplish this, we will again invoke bzr by issuing a command on the command line. Open up a terminal and navigate to the bzr directory in question. In our example, this would be  ~/my-blubuntu . Once there, issue  bzr add *  where:

1.  bzr 

   • This is the bzr program once again.

2.  add 

   • This is the parameter telling bzr that you wish to add files to your local instance -- or 'branch'.

3.  * 

   • This is the list of files you wish to add. In this case, it is a 'wildcard' and is telling bzr to simply add everything.

Q: Is that it? What do I do now?

Although this is an optional step, it is wise to get into the habit of checking what you have done. To do this, simply issue the  bzr diff  command where:

1.  bzr 

   • This is the bzr program invocation. As you can tell from all of this repetition, bzr wraps a lot of functionality into one small program. You will communicate with it throughout your experience with bzr.

2.  diff 

   • The 'diff' command instructs bzr that you would like to see the 'difference' between the last version and your last bzr action. It will produce a 'diff' output that should be relatively self explanatory. The parameter offers its heritage from the 'diff' *nix command.

Q: Done. Looks good. Can I tell bzr that my local branch is ready?

To do this, we will issue a 'commit' command via  bzr commit -m "This is my first commit -- Woo Hoo."  where:

1.  bzr 

   • Yep, you guessed it.

2.  commit 

   • Instructs bzr to 'commit' your changes into the internal record keeping system.

3.  -m "This is my first commit -- Woo Hoo." 

   • This is a comment. You should always provide a relatively good brief description of what you changed in your branch. This will all be accessible from the web interface once you upload your changes. If you leave the -m "comment" off of the  bzr commit  invocation, you will be presented with a full blown mini text editor to accomplish this task. All of this means that it is important, so don't treat your comments lightly.

Q: It doesn't seem like much has happened on my network connection. What do I do now?

Up to this point, you have merely been manipulating files on your local computer. In order to upload your changes to the central Bazaar server, we will invoke a final command. Note that you will not risk breaking any official packages with your changes. This is because the files that you are uploading are not being put into the development package. You will not be able to accomplish this until you have been granted access by your team or stepped through the proper protocols to have your changes 'merged' into the main package. So rest easy -- you won't be breaking all of Ubuntu by doing this. It is strictly a copy of your branch uploaded to a nice spot on the Bazaar server.

The invocation of bzr to push is  bzr push sftp://<launchpad-identity>@bazaar.launchpad.net/~<your-launchpad-id-or-team-id>/<product>/<branchname> . For our example, we might push something like  bzr push sftp://joe.blow@bazaar.launchpad.net/~joe.blow/blubuntu-look/joes-branch .

The syntax is worth noting:

1.  bzr 

   • Yet another use of the powerful bzr program.

2.  push 

   • The 'push' command tells bzr that you are ready to upload your committed changes from your local directory branch somewhere else. The following line tells bzr where you would like to put it.

3.  sftp://<launchpad-identity>@bazaar.launchpad.net/~<your-launchpad-id-or-team-id>/<product>/<branchname> 

   • Although a long command, this is simply an address. We will break it down further to see what is going on.

   •  sftp:// 

     • In this case we are going to use the sftp protocol (secure ftp based on ssh) to securely ship the contents to the given address. In order to push to the main Bazaar server, we need to identify ourselves to prevent unregistered people from uploading rubbish.

   •  <launchpad-identity> 

     • The <launchpad-identity> clause will always be your Launchpad I.D. as given on your Launchpad home page. This will automatically pull the uploaded ssh key from your Launchpad page and compare the result with your private key stored on your computer. Remember -- to upload you will need to have the public portion of your ssh key pair match the private portion on your computer. This is important if you plan on using more than one computer to use bzr with the public Bazaar server.

   •  @bazaar.launchpad.net 

     • Simply the address of the public server.

   •  /~<your-launchpad-id-or-team-id> 

     • This is a small but important detail. You can always upload a branch version under your Launchpad I.D. Sometimes it is useful to grant everyone on a given team permission to upload to the main branches to prevent the bookwork of merging the changes. To do this, you would replace your Launchpad I.D. with your Team Name / I.D. as given in Launchpad. Ultimately, Launchpad doesn't distinguish a difference between a team or a single person. The primary difference is that you can restrict access to a team, thereby providing a safe technique to prevent people from uploading improperly to certain branches.

   •  /<product> 

     • This is the primary package that you wish to upload to. If you create your own packages on Bazaar, you will need to register them through Launchpad before you can begin to upload changes via bzr. In our example, the package would be 'blubuntu-look'.

   •  /<branchname> 

     • This can be whatever you want if you are only uploading personal changes. This will keep 'versions' of your branch on the server under the given name. If you perhaps want to make more experimental changes, you could easily branch your local copy of files and push to an 'experimental' branch name.

All in all, the explanation is more complicated than the actual line. It is a single simple line to accomplish a push. In addition to this, once you have pushed your changes using the long format syntax, further pushes are all accomplished via stored variables from the directory. To do subsequent pushes, you need only type  bzr push  from within the directory.

The End of the Road or "The beginning of you and the Bazaar"

Hopefully you found this brief tutorial useful. It is not intended to be an exhaustive nor comprehensive document, but rather an easily scannable and yet explanatory tool. If you require extensive documentation for Bazaar, it is strongly encouraged that you read the man pages via  man bzr  on your computer. It explains the functions in full.

It is not without the immense help and patience of Daniel Holbach that this document was made possible. Hopefully future people can learn from this document, and save Daniel a little effort.

If you have any questions, comments, suggestions, complaints, or notice errors within this document -- feel free to contact the author of the page or any of its contributors.

Sincerely, TJS