Ubuntu Documentation - Desktop Getting Started
Ubuntu is all about community collaboration and the work we do together in order to produce a reliable world-class operating system. The same standards that apply to contributing to Ubuntu generally apply to contributing to Ubuntu Documentation.
Ubuntu Documentation is maintained by the Ubuntu Documentation Contributors Team with commit rights and administration by the Documentation Committers team and this page describes how you can start the journey of contributing to Ubuntu Documentation.
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
Launchpad is a system used to keep track of many aspects of open-source development. Launchpad's features include code hosting, bug tracking, translation, feature blueprints and a community-based answer tracker. This section will outline how to get setup with Launchpad to allow you to contribute the Ubuntu.
To find out more about Launchpad click here
Get a Launchpad account
The following steps will guide you through creating a Launchpad account:
Visit the Login/Register Page
- Enter your email and select "I am a new Ubuntu One user:"
- Enter your details as requested, agree to the "Terms of Service" and click "Create Account:
- Confirm your account by clicking on the link given in a confirmation email set to the email you provided
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. You are now ready to contribute to Ubuntu through Launchpad!
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 <firstname.lastname@example.org>" 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 a copy of the documentation development branch
The first step you will want to take to begin working on Ubuntu Documentation is to download a copy of the development branch of Ubuntu Documentation using Bazaar:
bzr branch lp:ubuntu-docs
Now that you have a local copy of Ubuntu Documentation you will want to become familiar with the anatomy of the Ubuntu Documentation branch. Mallard files will always be found in the path
Building html version of the docs
If you wish to just build the documentation as html to review them, follow these steps with your checked out branch:
cd ubuntu-docs/html/ make
The resulting documentation will end up in ~/ubuntu-docs/html/build/en/ which you can view in your web browser. More information on building the docs.
Editing Documentation Files
Improving Ubuntu Documentation is often as simple as opening the Mallard files in a command-line based text editor and reviewing them for minor changes like updating version numbers to the upcoming release number or checking for spelling and grammar.
In other cases for topic-oriented pages, it may be necessary to ensure that features have not significantly changed and if they have then update the documentation accordingly to reflect those changes.
Submit your changes for review
The next step you will want to take is to commit your changes using Bazaar by running the following commands:
bzr commit -m 'Brief one sentence summary of change goes here'
or if there is a related launchpad bug it can be linked in also:
bzr commit --fixes lp:123456 -m 'Brief one sentence summary of change goes here; LP: #123456'
or if there are multiple related launchpad bugs in this one commit, they can be linked:
bzr commit --fixes lp:123456 --fixes lp:123457 --fixes lp:123458 -m 'Brief one sentence summary of changes goes here; LP: #123456 LP: #123457 LP: #123458'
Then you will want to use Bazaar to push your changes to Launchpad:
bzr push lp:~bkerensa/ubuntu-docs/fix-for-foo
(fix-for-foo can also be fix-for-bugnumber if related to a bug or something else.)
Finally, you can propose your changes for merging by going to the Code section of your Launchpad account, select the appropriate branch, and submit a merge proposal ("Propose for merging"), or by running:
(This command will open your default web browser and, if you have granted Bazaar permission to interact with Launchpad, it will complete the process of opening a Merge Proposal that Ubuntu Documentation Committers can review.)
Creating Personal Sandbox Branch
If you log in to Launchpad and click the Code link at the top of the page, it will give you a bzr push command you can use to upload your sandbox work. Change BRANCHNAME in that command to whatever you want to call the sandbox you'd like to upload.
Since uploading to your own repo is standard practice for folks who aren't part of the core committers team, under "Submit your changes for review" there can be a note after `bzr push' saying that this can be used for simply "saving" your work in your own branch prior to merging as well.
This documentation is intended to be introductory but you can learn much more about Mallard through their own tutorials. You can always ask for help on Ubuntu Documentation Team’s mailing list or on #ubuntu-doc on Freenode IRC.
We look forward to seeing your contributions to Ubuntu Documentation and answering any questions that you may have.
I think that there is too much information, to the point where it gets confusing for the user reading it. To solve this, you could 1) Split the information into new, separate pages. 2) Remove some information that is not that useful - for example in the 'Get a Launchpad account', there is a lot of info which could be reduced to just the launchpad link together with a brief sentence to go with it, as in my opinion creating a launchpad account is pretty straight-forward. By doing this is some sections, you could greatly lower the amount of info. which would allow the user to understand the guide better