Ubuntu Wiki

Ubuntu Open Week - Docs Day - Getting the System Documentation - Bazaar - EmmaJane / MatthewEast - Tue, Apr 28th, 2009

(05:02:27 PM) emmajane: Hi everyone!
(05:02:42 PM) emmajane: In this next session I'm going to walk you through the very basics of using Bazaar to work with the Ubuntu System Documentation. Who's up for a little bit of version control?! :)
(05:03:11 PM) emmajane: crickets. :)
(05:03:26 PM) emmajane: more excitment over in the -chat channel, please
(05:03:35 PM) emmajane: who's ready for version control!? WOO!
(05:03:46 PM) emmajane: that's better. :)
(05:04:07 PM) emmajane: This session has several parts: (1) A little bit about Bazaar, (2) Installing Bazaar, (3) Using Bazaar for regular files (4) Downloading the system documentation, (5) Submitting your changes to the docs project and (6) Resources.
(05:04:41 PM) emmajane: I have the notes typed out if you are interested in reading ahead, please keep your questions to the topic at hand though, thanks. (just grabbing the pastebin URL)
(05:05:03 PM) emmajane: http://pastebin.ubuntu.com/160234/
(05:05:29 PM) emmajane: mdke is going to start us off with some "high level" talk about the tools we're using for system documentation.
(05:05:34 PM) emmajane: take it away, mdke
(05:05:47 PM) mdke: thanks
(05:05:49 PM) mdke: I just wanted to explain briefly what we mean by "System Documentation"
(05:06:02 PM) mdke: in case anyone missed Dougie's Introduction session
(05:06:26 PM) mdke: basically what we mean is the documentation that Ubuntu and other Ubuntu flavours (Kubuntu, Xubuntu, Edubuntu) include in their desktops
(05:06:36 PM) mdke: so in the case of Ubuntu, it's at System -> Help and Support
(05:06:55 PM) mdke: This documentation is "offline" so that any user of ubuntu can read it without going to the internet
(05:07:14 PM) mdke: It's also included online at https://help.ubuntu.com in identical form, in the case of Ubuntu
(05:07:44 PM) mdke: Given that the documentation is included in Ubuntu, we use some quality control processes to ensure that the material is carefully checked
(05:07:58 PM) mdke: a group of "committers" have access to add new material directly
(05:08:26 PM) mdke: and new contributors make requests for their changes to be approved
(05:08:43 PM) mdke: the system we use to manage this is called Bazaar, and it's what Emma will be concentrating on in this session
(05:08:59 PM) mdke: The documents themselves are written in a markup language called "Docbook", which is a bit like HTML
(05:09:10 PM) mdke: that's what Emma will talk about in the following session
(05:09:57 PM) emmajane: ok, thanks mdke
(05:10:40 PM) emmajane: Bazaar is "just" the storage tool for the system documentation. This talk applies to documentation and also anyone that wants to work with Ubuntu "code."
(05:10:55 PM) emmajane: Topic 1/6: A little bit about Bazaar
(05:11:02 PM) emmajane: Bazaar is a distributed version control system that Just Works. Bazaar adapts to the workflows you want to use, and it takes only a few minutes to try it out.
(05:11:13 PM) emmajane: Bazaar is used by all kinds of project teams to maintain all the changes that are made to the underlying code by each developer. In fact the code for the data base MySQL is stored in Bazaar! And Ubuntu is working towards putting 15,000 packages into Bazaar! These are HUGE projects!
(05:11:25 PM) emmajane: It can be used by real people too though. I like to think of myself as more of a "real person" than a "hardcore ninja developer." I use Bazaar because it's really good, but also because the support community is AMAZING. People have answered questions at all hours of the day in the IRC channel #bzr.
(05:11:40 PM) emmajane: Whether you're a hardcore ninja developer, or a real person, you can take advantage of version control for your work.
(05:11:40 PM) emmajane: (Apparently ninjas are real people too though.) ;)
(05:12:38 PM) emmajane: It can be useful to put all kinds of files under version control. For example: your configuration files, your resume, or any other kind of file that you might want to see a "historical" snapshot of.
(05:12:50 PM) emmajane: For example: I'm a freelance Web developer. I'm doing work on a client site and all of a sudden I get brand new files from the graphic designer that change everything. I could start a new folder, but that leaves a lot of junk lying around on my computer.
(05:12:57 PM) emmajane: Instead I use all the new files in my project (overwriting the old ones), but with Bazaar there is a secret "history" folder that allows me to go back and look at the old versions of the file whenever I want.
(05:13:05 PM) emmajane: I like to think of Bazaar as the biggest, baddest UNDO button my computer has ever known.
(05:13:22 PM) emmajane: I'm going to pause here and collect questions from #ubuntu-classroom-chat
(05:14:21 PM) emmajane: <jtholmes> Question: i take it bazaar can also run on a personal computer with little setup effort?
(05:14:42 PM) emmajane: Absolutely! In fact we're going to set it up in the very next part of this talk.
(05:15:04 PM) emmajane: <dinda> QUESTION: Can Bzr be used for text-based files?  or just html/xml?
(05:15:46 PM) emmajane: Bazaar can be used to create versions of any files. It is most effective with plain text files (like HTML, XML and configuration files), but it can also be used to store images too!
(05:16:03 PM) emmajane: <TaNgO> Question: I'm using SVN at the moment... It's first time I heard about Bazaar. Why should I switch to it?
(05:16:52 PM) emmajane: TaNgO, Great question! If you like SVN, you should keep using it. If, however, you want to be able to work directly with the system documentation, having a rudimentary understanding of the basic bzr commands will make it a lot easier.
(05:17:09 PM) emmajane: TaNgO, there's also cool plugins that make Bazaar work with SVN.
(05:17:20 PM) emmajane: <zaidka> QUESTION: Why using Bazaar instead of a wiki?
(05:18:30 PM) emmajane: Bazaar has a more sophisticated versioning system than you can get in a Wiki. On top of that it's only recently that Wikis have been able to convert text into different formats. In some ways working with Bazaar and DocBook is a legacy system, but it also allows a greater degree of control on how the documents look in their final stage (e.g. PDF or HTML).
(05:18:59 PM) mdke: the tools to convert wiki material into docbook are a little bit incomplete at the moment
(05:19:15 PM) mdke: and as emmajane says, Bazaar allows more finely grained version control tools
(05:19:32 PM) mdke: but in the future, we will definitely keep looking at using a wiki for system documentation - I hope one day it will be possible
(05:20:16 PM) emmajane: Topic 2/6: Installing Bazaar
(05:20:26 PM) emmajane: I'm going to assume that everyone is already using Ubuntu?
(05:20:51 PM) emmajane: Is anyone on something OTHER than Ubuntu right now though? I know you might be secretly connected at work right now where you're forced to use something else...
(05:21:25 PM) emmajane: We will be working from the command line for most of this session. I am very comfortable at the command line so if I go too quickly, please jump up and down and tell me! I have used the convention of $ to mean start typing a command. If you look at your command line you will see that it ends with a $. Mine looks like this:
(05:21:25 PM) emmajane: emmajane@hum:~$
(05:21:45 PM) emmajane: If you are using GNOME you can open a new terminal window by navigating to:
(05:21:45 PM) emmajane: Applications (top left of your screen) -> Accessories -> Terminal.
(05:21:54 PM) emmajane: (GNOME is the default for Ubuntu)
(05:22:09 PM) emmajane: If you are using KDE you can open a new terminal window by navigating to:
(05:22:09 PM) emmajane: System -> Terminal Program (Konsole)
(05:22:21 PM) emmajane: If you are using a different desktop environment you are probably already a super 1337 haX0r that knows how to find a terminal window, but please let me know if you need more help!
(05:22:32 PM) emmajane: Let me know if you can't find a terminal window....
(05:23:50 PM) emmajane: Now that you are at the terminal window you will see something similar to my command line that I displayed above. We are now going to install Bazaar. I chose to do this from the command because that's where we'll be running the commands. You could also use the Synaptic Package Manager to do this installation.
(05:24:06 PM) emmajane: To install Bazaar we are going to use a package manager called apt-get. It install a package it uses the structure: apt-get install PACKAGENAME. You must be the super user of your system to run this program we will use the "sudo" command instead because it's faster and because this comic is funnier if you know about sudo:  http://xkcd.com/149/
(05:24:22 PM) emmajane: $ sudo apt-get install bzr
(05:25:16 PM) emmajane: You will be prompted for your password. This is your password.
(05:25:24 PM) emmajane: (Assuming you are the only "user" on your workstation)
(05:26:53 PM) emmajane: <dinda> how do i know if i have the latest version of bzr installed?
(05:27:16 PM) emmajane: If you run that command Ubuntu will check to see if your version is already the latest for your version of Ubuntu.
(05:27:44 PM) emmajane: Assuming you have automatic updates turned on (yes by default) you are probably already running the latest version for your flavour of Ubuntu.
(05:29:16 PM) emmajane: Assuming that worked you should now have Bazaar installed on your system. You can test this with the following command:
(05:29:16 PM) emmajane: $ bzr
(05:29:25 PM) emmajane: You should get a list of Bazaar commands. Note: Bazaar is the name of the application and bzr is the actual command that you run.
(05:30:17 PM) emmajane: The first command we're going to run "in" Bazaar is to tell it who you are. This will put your name next to any work that you do with the system documentation.
(05:30:22 PM) emmajane: $ bzr whoami "Your name <youremail@ubuntu.com>"
(05:30:44 PM) emmajane: You should replace "Your name" with your actual name. The email address is optional.
(05:31:27 PM) emmajane: See how bzr is a command line utility?
(05:31:45 PM) emmajane: You type in "bzr" and the command you want to give it. In this case it's bzr whoami
(05:31:50 PM) emmajane: If you want to have a pointy-clicky browser to make these changes you can also install "Olive." This program has the package name: bzr-gtk. You can install it with the following command:
(05:31:58 PM) emmajane: $ sudo apt-get install bzr-gtk
(05:32:13 PM) emmajane: I'll be honest though, the command line version of the tool is a lot more robust.
(05:32:30 PM) emmajane: There are also tools for Windows and OSX too.
(05:32:48 PM) emmajane: A few months ago I prepared a screen cast for the Desktop Training Course, although the package that you download for the system documentation is different, many of the concepts are the same. You can watch the video here:
(05:32:48 PM) emmajane: http://showmedo.com/videotutorials/video?name=3670000&fromSeriesID=367
(05:33:07 PM) emmajane: You can watch that screen cast later...
(05:33:09 PM) emmajane: How's everyone doing so far? Ready to start taking snapshots of your files?
(05:33:21 PM) emmajane: <zaidka> QUESTION: is bazaar a distributed version control system? or centralized like subversion?
(05:33:41 PM) emmajane: Bazaar is a distributed version control system. It's like Git or Mercurial.
(05:33:56 PM) emmajane: It can behave like a centralized system as well (like CVS or Subversion).
(05:34:36 PM) emmajane: http://bazaar-vcs.org/Workflows <-- those are a few of the ways you can set up Bazaar.
(05:34:59 PM) emmajane: the documentation team uses Bazaar with a "centralized" model meaning that everyone checks their files into Launchpad.
(05:35:16 PM) emmajane: Topic 3/6: Using Bazaar for regular files
(05:35:26 PM) emmajane: For the next part I want you to choose a directory that has files you *know* you should be keeping in better order. This might be an application that you've been hacking away on, or your resume folder, or whatever!
(05:35:38 PM) emmajane: We could also invent some files if you wanted to, but I think it's nice to work with files you know.
(05:35:49 PM) emmajane: Change directory to the folder that has the files you want to put under revision control. I am going to work in the folder that contains the files for the Web site bzrvsgit.com. I use the following command to move to that directory:
(05:35:49 PM) emmajane: $ cd websites/bzrvsgit.com
(05:36:10 PM) emmajane: Remember that you can use the tab button to finish typing each of the words. Type the first letter of the file name and then press the tab key. It will type the rest of the word for you. Of course if there are more than one files that start with the same letter you will need to type a few more letters before hitting tab again.
(05:37:03 PM) emmajane: Once you have changed to your working directory you can create a new "repository" of your files. A repository is a place where data are stored and maintained. This folder will no longer be a simple set of files. It will be an uber awesome time machine that lets you travel back in time to see old versions of your files.
(05:37:10 PM) emmajane: To start the time machine, I mean initialize the repository, use the following command:
(05:37:10 PM) emmajane: $ bzr init
(05:38:04 PM) emmajane: It's sort of like a magic trick because you won't see anything happen. This command creates a hidden time machine in your current directory.
(05:38:10 PM) emmajane: You can confirm it is there with the following command:
(05:38:10 PM) emmajane: $ ls -al
(05:38:18 PM) emmajane: Do you see the .bzr folder? That's your time machine!
(05:38:37 PM) emmajane: Has everyone got their time machine?
(05:38:37 PM) emmajane: I mean .bzr folder?
(05:39:44 PM) emmajane: <dinda> so this is all happening locally and not interacting with anything on the web right?
(05:39:47 PM) emmajane: Correct!
(05:40:10 PM) emmajane: Right now you're like a little pod inside a space ship waiting to get launched.
(05:40:21 PM) emmajane: <jtholmes> QUESTION: did canonical folks write bazaar
(05:40:50 PM) emmajane: Sort of. They sponsor the project currently and have re-written nearly the entire code base, but they didn't start the project initially.
(05:41:44 PM) emmajane: I did a quick google for the history of the project, but I'm not seeing it. If anyone wants to paste it into -chat I'll put the URL here later on.
(05:42:07 PM) emmajane: I'm going to move onto the next step...
(05:42:08 PM) emmajane: For the next step you need to add all your files into the time machine. This command tells Bazaar there are new files being added to the repository. It doesn't save any changes, it just tells Bazaar which files it ought to be monitoring. To add files to the repository, use the following command:
(05:42:08 PM) emmajane: $ bzr add
(05:42:35 PM) emmajane: History of the Bazaar project at: http://en.wikipedia.org/wiki/Bazaar_(software)#History (thanks mdke!)
(05:42:58 PM) emmajane: Bazaar will tell you that it has added the files to the time machine. Next you will need to lock and load the time machine. This allows you to jump back to this point in history. In Bazaar-speak this is referred to as "committing your changes."
(05:43:05 PM) emmajane: You must add a little message each time you commit your files. This lets you know what happened at this point in history (and makes it easier to jump back in time to exactly the right point). Be descriptive in your commit message. Use the following command:
(05:43:06 PM) emmajane: $ bzr commit -m "Adding files to the time machine for the very first time."
(05:43:48 PM) emmajane: <jtholmes> QUESTION: if you add a new file to the directory does bazaar know the others have already been added
(05:44:08 PM) emmajane: Not automatically. You have to tell it about any new files that you create or copy into that folder by using the same command (bzr add).
(05:44:57 PM) emmajane: Just a little side note: please do not send me Private Messages with your questions. Please join the channel: #ubuntu-classroom-chat
(05:44:59 PM) emmajane: Thanks!!
(05:45:19 PM) emmajane: <Wess> Question: Do we have to add the files one by one or can we use wild card *
(05:45:38 PM) emmajane: All of the files in the directory will automatically be added. You don't need to worry about using a wild card.
(05:45:59 PM) emmajane: Once you've got the files "added" try doing your first commit.
(05:46:44 PM) emmajane: Then try editing one of the files and "committing" again.
(05:47:36 PM) emmajane: <amigo_rich> QUESTION: Can I change the editor from nano to something else?
(05:48:01 PM) emmajane: If you use the -m parameter you can completely bypass the editor.
(05:48:59 PM) mdke: You can change the editor that you system uses automatically with the command: $ update-alternatives --config editor
(05:49:08 PM) emmajane: Now that you've seen how easy it is to issue commands to Bazaar, we're going to download the Ubuntu system documentation. On my "fast" connection this took about 5 minutes.
(05:49:28 PM) emmajane: Topic 4/6: Downloading the system documentation
(05:50:04 PM) emmajane: This time we're going to issue a command to Bazaar to tell it to go and get the system documentation from the hosting platform, Launchpad.
(05:50:07 PM) emmajane: here's the command:
(05:50:09 PM) emmajane: $ bzr branch lp:ubuntu-doc
(05:50:16 PM) emmajane: let's take a look at it:
(05:50:26 PM) emmajane: bzr <--- you know that part. You've already used it a couple of times.
(05:50:45 PM) emmajane: branch <--- this is telling Launchpad that you'd like to grab a new copy of the system documentation.
(05:51:04 PM) emmajane: lp:ubuntu-doc <--- this part actually says which bits to download.
(05:51:10 PM) emmajane: branch means "new copy"
(05:51:23 PM) emmajane: WAIT THOUGH
(05:51:34 PM) emmajane: this is going to download to wherever you currently are!
(05:51:47 PM) emmajane: you may want to change directories first!
(05:52:13 PM) emmajane: If it has already started downloading, simply use: control-c to "cancel" the download.
(05:52:49 PM) emmajane: so if you want to put the files into your home directory, use the following:
(05:52:54 PM) emmajane: $ cd
(05:53:03 PM) emmajane: $ bzr branch lp:ubuntu-doc
(05:54:04 PM) emmajane: You will see the following error message:
(05:54:04 PM) emmajane: You have not informed bzr of your Launchpad ID, and you must do this to write to Launchpad or access private data.  See "bzr help launchpad-login".
(05:54:04 PM) emmajane: Because you do not have "write" access, you can safely ignore this message for now. If you want to register yourself with launchpad you will need to follow the instructions at: https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Repository#Generating%20SSH%20keys
(05:54:48 PM) emmajane: In the pastebin for this talk I have more advanced instructions for more complicated setups. I won't have time to cover them, but you can ask me about them later!
(05:55:39 PM) emmajane: <zaidka> FOLLOWUP QUESTION: Then how does bazaar know which server to grab the data from?
(05:55:39 PM) emmajane: zaidka, LP means "from launchpad" which is the centralized server we use.
(05:56:05 PM) emmajane: You should now be in the process of downloading the Ubuntu system documentation source files!
(05:57:13 PM) emmajane: While you download those files, let's take a look at what you'll find once they're downloaded.
(05:57:16 PM) emmajane: The documents that can be edited appear in the top level of the branch. Documents use the structure documentname/C/documentname.xml. The C directory represents the default language of the system (in our case, English). Translations of each document are found in the documentname/po directory.
(05:57:27 PM) emmajane: There are some directories there which do not correspond to documents. These are briefly explained as follows:
(05:57:38 PM) emmajane:     * build/ - this is where HTML versions of the documents are put when generated as explained on the Building Documentation page.
(05:57:38 PM) emmajane:     * debian/ - this contains the files used to generate an Ubuntu package from the branch. For more information on packaging, see the PackagingGuide page.
(05:57:38 PM) emmajane:     * libs/ - this contains the files used to generate HTML and PDF from the documents.
(05:57:38 PM) emmajane:     * scripts/ - this contains specific scripts which are used by the team for various tasks, especially translation.
(05:58:47 PM) emmajane: I'm going to motor through the last little bit as you're downloading the files.
(05:58:49 PM) emmajane: Topic 5/6: Submitting your changes
(05:58:59 PM) emmajane: There are several ways to submit your requested changes for system documentation. I will cover two here: bzr bundle (submitted via the Launchpad Web interface); and bzr push.
(05:59:08 PM) emmajane: Bazaar bundles are text files that allow the reviewer to "merge" your changes into the main branch for the documentation. They are similar to a "diff" file, but contain additional information. They are simple to create. Once you have made all of your changes (and committed them), use the following steps:
(05:59:20 PM) emmajane: $ cd ~/ubuntu-doc (or wherever the root directory is for your changed branch)
(05:59:31 PM) emmajane: $ bzr bundle > ~/Desktop/my-documentation-changes.patch
(05:59:31 PM) emmajane: Now you have a patch file that can be submitted back to the team. At this point the most effective way of having that change seen is to submit a new bug report in Launchpad and attach the file.
(05:59:42 PM) emmajane: The bugs page for the team is available at:
(05:59:42 PM) emmajane: https://bugs.edge.launchpad.net/ubuntu-doc
(06:00:29 PM) emmajane: A few months ago I prepared a screen cast which explains the second method to "push" your changes back to Launchpad. The file names are relevant to the Desktop course, but the concepts are the same. You can watch the video here:
(06:00:30 PM) emmajane: http://showmedo.com/videotutorials/video?name=3680000&fromSeriesID=368
(06:01:08 PM) emmajane: We can go into more detail as part of the DocBook session (if you're sticking around).
(06:01:23 PM) emmajane: Finally I want to end with some Bazaar resources.
(06:01:26 PM) emmajane: Topic 6/6: Resources
(06:01:26 PM) emmajane: There are lots of resources to learn more about Bazaar if you want to use it for more than just Ubuntu system documentation.
(06:01:26 PM) emmajane: The built-in documentation is really good. You can check the "man" pages with:
(06:01:26 PM) emmajane: $ man bzr
(06:01:26 PM) emmajane: OR get a list of all the commands in bzr with:
(06:01:28 PM) emmajane: $ bzr --help commands
(06:01:30 PM) emmajane: OR list the table of contents for the help files with:
(06:01:32 PM) emmajane: $ bzr help topics
(06:01:34 PM) emmajane: OR you can join the IRC channel or the bazaar mailing list!
(06:01:36 PM) emmajane: IRC: #bzr
(06:01:38 PM) emmajane: mailing list: bazaar@lists.canonical.com
(06:01:49 PM) emmajane: There were some AMAZING questions today, thanks everyone.
(06:02:17 PM) mdke: great job at answering them all!
(06:02:18 PM) emmajane: I'm going to take a short break, but then roll into the DocBook talk which explains what to do with those files you're currently downloading.
(06:02:25 PM) emmajane: Hopefully everyone can stick around for the second part!