About The Repository
The documentation sources for the project reside in Bazaar, a revision management system created by Canonical, the company behind Ubuntu. The repository is the hub of the core document development effort. Revision control helps us to work on the same files simultaneously without “clobbering” each others work. Any author wanting to contribute to the documentation effort can checkout their own branch or working copy of the documentation sources and make changes to this copy.
If you have never worked with a version control system, don't be nervous - you cannot break anything in the repository, only your local, working copy. This is because you will be working as an anonymous user and therefore do not have the permissions to change anything in the repository. Only people with commit access can make changes to the repository. People are given access once they have consistently provided contributions and demonstrated commitment.
Key Bzr Branches
A complete list of the key Doc Team Bazaar branches is available on Launchpad.
The key branches which will be of most interest are:
Name of Branch
Ubuntu desktop help
Xubuntu desktop help
Ubuntu Server Guide
Generally you should use the development version for each branch.
Tools for Ubuntu Documentation Work Flow
To be able to contribute to Ubuntu Documentation some tools will be required. So we will start by installing the following:
sudo apt-get install bzr xsltproc libxml2-utils yelp-tools yelp-xsl make
The command will install the following software (and possibly many additional dependent packages):
- bzr – distributed version control. Bazaar, a new way of working with packages for Ubuntu that will make it easy for many developers to collaborate and work on the same code while keeping it trivial to merge each other’s work.
- xsltproc - XSLT command line processor.
- libxml2-utils - XML utilities.
- yelp-tools - Yelp documentation tools.
- yelp-xsl - XSL stylesheets for the yelp help browser.
- make - a utility for Directing compilation.
Xubuntu and the Serverguide use Docbook, and therefore require additional packages:
sudo apt-get install docbook docbook-xsl
- docbook - standard SGML representation system for technical documents
docbook-xsl - stylesheets for processing DocBook XML to various output formats
Additionally only the serverguide project requires another couple of packages:
sudo apt-get install fop gnome-doc-utils
- fop - XML formatter driven by XSL Formatting Objects
- gnome-doc-utils - collection of documentation utilities for the GNOME project
Create your SSH key
SSH stands for Secure Shell, and it is a protocol that allows you to exchange data in a secure way over a network. It is common to use SSH to access and open a shell on another computer, and to use it to securely transfer files. For our purposes, we will mainly be using SSH to securely upload source packages to Launchpad.
No previous SSH key
To generate an SSH key, enter:
ssh-keygen -t rsa
Accept the default file name id_rsa. For security purposes, it is highly recommended that you use a pass-phrase.
SSH key generated previously
If you already have an id_rsa SSH key that you use for some other purpose but accessing Launchpad, there are two options:
Don't generate another key, but copy the public key from the already existing id_rsa.pub when asked to upload your key to Launchpad.
Get set up to work with Launchpad
With a basic local configuration in place, your next step will be to configure your system to work with Launchpad. This section will focus on the following topics: What Launchpad is and creating a Launchpad account Uploading your GPG and SSH keys to Launchpad Configuring Bazaar to work with Launchpad Configuring Bash to work with Bazaar
Launchpad is the central piece of infrastructure we use in Ubuntu. It not only stores our packages and our code, but also things like translations, bug reports, and information about the people who work on Ubuntu and their team memberships. You will also use Launchpad to publish your proposed fixes, and get other Ubuntu developers to review and sponsor them. You will need to register with Launchpad and provide a minimal amount of information. This will allow you to download and upload code, submit bug reports, and more. Besides hosting Ubuntu, Launchpad can host any Free Software project. For more information see the Launchpad Help wiki.
Get a Launchpad account
If you don’t already have a Launchpad account, you can easily create one. If you have a Launchpad account but cannot remember your Launchpad id, you can find this out by going to https://launchpad.net/~ and looking for the part after the ~ in the URL. Launchpad’s registration process will ask you to choose a display name. It is encouraged for you to use your real name here so that your Ubuntu developer colleagues will be able to get to know you better. When you register a new account, Launchpad will send you an email with a link you need to open in your browser in order to verify your email address. If you don’t receive it, check in your spam folder. The new account help page on Launchpad has more information about the process and additional settings you can change.
Upload your SSH key to Launchpad
Open https://launchpad.net/~/+editsshkeys in a web browser, also open ~/.ssh/id_rsa.pub in a text editor. This is the public part of your SSH key, so it is safe to share it with Launchpad. Copy the contents of the file and paste them into the text box on the web page that says “Add an SSH key”. Now click “Import Public Key”. For more information on this process, visit the creating an SSH keypair page on Launchpad.
Bazaar is the tool we use to store code changes in a logical way, to exchange proposed changes and merge them, even if development is done concurrently. It is used for the new Ubuntu Distributed Development method of working with Ubuntu packages. To tell Bazaar who you are, simply run:
bzr whoami "Bob Dobbs <email@example.com>" bzr launchpad-login subgenius
whoami will tell Bazaar which name and email address it should use for your commit messages. With launchpad-login you set your Launchpad ID. This way code that you publish in Launchpad will be associated with you. Note: If you can not remember the ID, go to https://launchpad.net/~ and see where it redirects you. The part after the “~” in the URL is your Launchpad ID.)
Even if the rest of this page describes terminal commands for working with Bazaar branches, there are GUI applications available that appeal to some contributors. One such application that you may want to try is Bazaar Explorer.
sudo apt-get install bzr-explorer
Getting the docs
To make changes to documentation held in a Bazaar branch, you first need to download a copy onto your computer.
The first step is to identify the particular Bazaar branch which you want to download. The Doc Team works with several different branches. A list is at the top of this page. Choose your branch, and follow these instructions.
On a GUI based system, open a Terminal by pressing Applications -> Accessories -> Terminal. Of course, a server based system only has terminals.
Type mkdir ubuntu_bzr and press enter. This will create a new directory called ubuntu_bzr in your Home directory. Of course, you can create a directory with a different name and in a different location.
Type cd ubuntu_bzr to change to the new directory.
Type bzr lp:name_of_branch into the Terminal. This will download the whole of the branch, which you will then be able to modify using a text editor.
You can get the name of the branch which you want from the list on Launchpad. The current development branches for each flavor of Ubuntu appear with a star by their name in that list.
- Current development examples:
$ bzr branch lp:ubuntu-docs
$ bzr branch lp:serverguide
$ bzr branch lp:xubuntu-docs
- Previous release examples:
$ bzr branch lp:ubuntu-docs/precise
$ bzr branch lp:serverguide/precise
$ bzr branch lp:xubuntu-docs/precise
This process may take quite a while, as it downloads the whole of the revision history in the branch. See Advanced below for ways to speed up this process.
Updating a check-out
You will probably want to keep up-to-date with changes made to the documentation. To download the latest updates to a branch:
- Open a Terminal.
- Change to the directory which contains your original checkout (e.g. ubuntu_bzr/name_of_branch, as above).
Type bzr update and any updates will be downloaded.
Once you have downloaded a branch, the next step is to view and edit the documents contained within it. Read on to the Editing page.
Some tips for people who have been granted permissions to upload directly to the system documentation branches (by becoming members of the ubuntu-core-doc team) can be found at the /Members page. If you are just getting started with Ubuntu documentation, you don't need to read that page yet.