Install python-nautilus and experimental bzr-gtk (http://packages.debian.org/experimental/all/bzr-gtk/download)
The Bazaar or "An Explanation of Bazaar for the (Almost) Typical Contributor"
Q: What is Bazaar?
From the 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 very difficult, but not many people have been exposed to the program before.
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' realm. This might include sound packagers, art packagers, documentation packagers, etc. This document seeks to target those participants and elevate their integration with Ubuntu development.
Q: I have heard that Bazaar integrates with Launchpad, is this true?
Yes. One of the most powerful aspects to 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. In the world of Free Software, this centralization of distribution is priceless.
Q: Bazaar sounds complicated, is it?
No. Getting up to speed is very easy. If you want people to collaborate on your project, 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 is a tool used to provide secure transmission across a network. The default Bazaar repository relies on it to validate all connections. This means that in order to be able to put things on the Launchpad 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 <email@example.com>" . The cryptic command is very easy to understand when broken down into its discreet parts:
- This command invokes the key generator program.
This parameter instructs the key generator what type of key you would like. There are many types of encryption out there, and in this example, the -t sets the encryption type to RSA -- man ssh-keygen for more information.
- A comment. Good for keeping track of what a certain key does. As you can guess, you can have many keys, and comments are terrific for keeping your brain from exploding.
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 Nautilus 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:
This is your private key. Never give that one out.
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 https://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 branch https://code.launchpad.net/~ubuntu-art-pkg/+branch/blubuntu-look/ubuntu my-blubuntu
The syntax is quite simple:
- This will invoke the bzr program.
- This is a parameter, or mini-command, that describes what you want bzr to 'do' -- in this case -- you want to create a local 'branch' of the project, which will pull all of the package source to your local computer.
- This is the full link that is obtainable from the above Launchpad search described above.
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 HTTP 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 and 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.
Q: I have heard that there is a 'checkout' version that does something like 'branch'. When should I use it?
"bzr branch" will create a standalone copy of the branch on Launchpad. "bzr checkout" will create a local branch that is bound to the branch on Launchpad. Whenever you make a commit locally in a checkout, it will also automatically be committed to the branch in Launchpad.
Q: If I change a branch then, will it show up in the web interface or is it lost in the ether?
As long as the official package name matches after you upload your changes, it should show up in the revision history. Don't assume that anything will happen with it though, as it still requires due diligence to talk to the proper parties involved to see your changes merged.
Returning to the Bazaar or "Setting up shop at the Bazaar"
So you have downloaded the source code for the project in a 'branch' format so you can make changes. 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 the package.
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 branched 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:
- This is the bzr program once again.
- This is the parameter telling bzr that you wish to add files to your local instance -- or 'branch'.
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. In this case, the wildcard is optional, as bzr add alone would assume you wish to add all files.
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:
- 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.
- 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:
- Yep, you guessed it.
- Instructs bzr to 'commit' your changes into the internal record keeping system.
-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 too 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 telling 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://firstname.lastname@example.org/~joe.blow/blubuntu-look/joes-branch .
The syntax is worth noting:
- Yet another use of the powerful bzr program.
- 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.
- Although a long command, this is simply an address. We will break it down further to see what is going on.
- 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.
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.
- Simply the address of the public server.
- 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.
- 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', which has already been registered.
- 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, once you have pushed your changes using the long format syntax, further pushes are all accomplished via stored variables in a hidden files. To do subsequent pushes, you need only type bzr push from within the directory -- no need for that massive URL string anymore!
Q: I have pushed my package! What now?
Now you will need to notify the maintainer of the package or a developer with the agency to merge your changes into the main package. They will be able to examine your changes, decide on revisions possibly, and ultimately -- if they agree -- merge your changes into the main branch. Figuring out exactly who does what can be quite a chore -- but Launchpad should provide you with all the details necessary to at least get your query into the proper hands. Start clicking those web links...
Bazaar on the Frontier or "How do I create something new and fresh for Ubuntu?"
You have pulled a few packages, examined them, and started to get acquainted with the powerful tool known as Bazaar. You have even pushed a few simple changes you made to Bazaar, and maybe even saw them get committed into the main branch. Now, you have a project that you would love to see used in Ubuntu. You realize that Bazaar will probably be the best way to host it and have it quickly integrated into the system. The following section attempts to address new branches, splitting branches, and like areas.
Q: Why might I want to have my own branch?
Have you ever had that Ubuntu itch that makes you wish you could create a package and make it available to the users of Ubuntu? Maybe it is a set of wallpapers, sound design scheme, or even documentation in a local copy? Creating your own branch is the best way to accomplish this, and utilizing the primary tools of Ubuntu helps to make this transition easier for the people who can make your wish a reality.
Q: I'm sold on the idea! I want to start my own branch! How do I do this?
Bear in mind that before something can be accepted into the mainstream light, you might want to consider some of the 'policies' that will bind your package. For example, Debian has very strict policies regarding licensing, files, directory layout, etc. If your ultimate goal is to have it be an official package, you should probably lay down a little groundwork by researching the policies that will be applied to your package.
The following process assumes that you are familiar with the policies of your destination. Remember, if you just want to develop something on your own, you don't need policies at all. That said, it will be easier to set those policies in place early rather than try and retrofit a bunch of files after your project has ballooned in complexity.
To set the process into motion, we will establish roughly what we expect our layout will be on our local system. Let's assume that we are starting our own small package of wallpapers. To do this, we will ignore the issues of policies for now, as they are beyond the scope of this document. Let's create a local directory on our computer. It will have the following layout:
~/wallpaper-package ~/wallpaper-package/foobar.png ~/wallpaper-package/helloworld.png ~/wallpaper-package/rtfm.png
Q: Done. Now what? I bet it is 'bzr add' like we did above correct?
Not quite. Since all we have done at this point is create a normal directory structure on our system, bzr knows nothing about what is going on. A critical step is required to set up bzr for the directory -- bzr init -- which kickstarts the bzr process for that directory. It must be executed from within the directory in question. So, as per our example, we would change directories to get inside of the ~/wallpaper-package directory, then issue bzr init once there.
Q: Did that. Nothing appeared to happen. No files. Nothing. What happened?
Remember our discussion about how bzr does a lot of things 'behind-the-scenes'? If you view all hidden files in that directory, you will see that a little hidden directory called .bzr was created. Within that directory is all of the basic structure that bzr will need for future operations. You only need to issue bzr init once per freshly created directory tree.
Q: Ok. That is clearer. Now what do I do? 'add'?
Yes. Now the pattern follows what we laid out above. Add the files either explicitly, or use wildcards. bzr add * will output a listing of all files that are now tracked by bzr.
Q: Starting to get this... I commit now correct?
Once again, try to get into the habit of 'diff'. It is a good way to validate your changes before you commit. bzr diff is the syntax in the event that you forgot.
Q: Ahh yes. Ok. I performed the 'diff'. Looks good. 'commit' the changes now correct?
At this point it is safe to make your changes official to bzr. bzr commit -m "First commit with three wallpapers." should do the trick.
Q: And now the upload, or 'push', right?
Not quite. Remember that when we were uploading our changes before we had a product name to push to. You will need a 'product' too if you want to expose the package to the useful tools that Launchpad and Bazaar have to offer. To add a product, explore http://www.launchpad.net/products further. In the upper left, is a link to register a new product, which is what we will need to do in order to establish all the proper links on the server. Fill out the basics, and you will quickly have a new product registered.
Q: Doesn't this seem a bit excessive? I am just uploading a package of wallpapers.
Remember that once you get a package into the repositories you will have (hopefully) many users downloading your work. As a result, unforeseen features may arise. Some people call those bugs. Again, part of the power of Launchpad and its brothers and sisters is the interrelatedness of their abilities. Malone, for example, tracks bugs. Now with a registered product that properly identifies itself with Malone, users can register bugs against your package, and in some instances, fix them for you. All of this would be quite a nightmare without the 'glue' that Launchpad, Bazaar, and Malone provide. For our example, let's assume you create a product named "wallpapers-r-us".
Q: I never really looked at it that way. Ok, I now have a product. Now what?
Now we are free to push our changes and have them automagically reflected throughout Launchpad. Pretty impressive for a few simple steps, as you will see. Again, the loose syntax for a push is bzr push sftp://<launchpad-identity>@bazaar.launchpad.net/~<your-launchpad-id-or-team-id>/<product>/<branchname> . As per our example, this loosely translates into bzr push sftp://email@example.com/~joe.blow/wallpapers-r-us/dev-branch .
Q: Do I need subbranches really?
Probably not, until your project grows to a size that requires it. That said, it is useful to see the syntax. If you are an organizational stickler, this also might be appealing. Remember though, bzr has many powerful tools to adjust based on version histories. As a simple rule, keep things as simple as possible until you clearly need to make things more complicated.
Q: Ok. Done. Now what?
Well, had this been a real series of events, all of our work would be nicely formatted and centralized on Launchpad now. For example, consider the following links. The links provided here pertain to the "ubuntu-artwork" product. Simply replace the product name with your related name for customized output:
- The root page. All sorts of valuable information is contained on this page. The true power comes from accessing both the left panel links and certain HTML phrases that you could easily add to the address line.
- Clicking the 'Code' link from the left panel yields this page. 'Code' might seem a little deceptive if you are developing artwork, sounds, documents, etc. It is where you will find all of the changes you pushed through bzr.
- Clicking on the resulting Bazaar package link takes us to this page. Notice the activity that is reported. Notice how your 'commit' messages are shown in the listing. Again, the complexity increases as you follow down the branches.
As you can see from this short example, there is a huge amount of power, customization, control, and other details that you can extract from having an officially registered product at Launchpad.
More to Come
As with all Wiki pages, this is an evolving document.
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 many folks that this document is made possible. The Ubuntu community has really led the wave of spreading education through the application of patience and personal interaction. Without the following individuals, this information would be locked away in a cave somewhere:
- Daniel Holbach
If you don't know who Daniel is, just ask someone who has been around Ubuntu for a while. A workhorse. He doesn't just answer questions or send out email -- this guy actually does the things that the completely code befuddled typical joe couldn't do. In particular, he has put up with more questions, silly questions, and damn stupid questions than any person should need to.
- John A Meinel
- One of the people who works on this amazing tool called Bazaar. He too has had his fair share of silly questions asked in ways that only a master decrypter might be able to understand. Thanks go to him for taking the time to help spread the word to less technically inclined folks.
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.