Ubuntu Wiki

Ubuntu Documentation - Getting Started

DO NOT EDIT THIS PAGE!!! IT IS HERE ONLY FOR THE EDIT HISTORY.

Introduction

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

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.

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.

To generate an SSH key, enter:

ssh-keygen -t rsa

The default file name usually makes sense, so you can just leave it as it is. For security purposes, it is highly recommended that you use a pass-phrase.

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

About Launchpad

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.

Configure Bazaar

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 <subgenius@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.)

Getting Started with Ubuntu Documentation

Ubuntu Documentation uses the Mallard markup language for its offline documentation that ships with each release of Ubuntu. Mallard makes contributing to Ubuntu Documentation easy for almost anyone to dive into.

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

~/ubuntu-docs/ubuntu-help/C.

??? Add more

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'

Then you will want to use Bazaar to push your changes to Launchpad:

bzr push lp:~bkerensa/ubuntu/saucy/ubuntu-doc/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:

bzr lp-propose

(This command will open your default web-browser and if you have granted Bazaar permission to interact with Launchpad it will complete the propose of opening a Merge Proposal that Ubuntu Documentation Committers can review)

Ubuntu Community Wiki

Anyone with a LaunchPad account can edit the Ubuntu Comminuty Wiki. There three main methods of working on wiki pages:

• On the page itself

  Sandbox Wiki pages

  Offline MoinMoin wiki

On the page itself

Go to the page that you want to edit. On the top of this page, under the "Ubuntu Wiki" banner, there is a button called, "Edit". This button allows you go into editting mode where you can work on the page that you need without messing up the real page. Make sure you save this page when you are done editting it!

Sandbox Wiki pages

What are Sandbox Pages?

These pages are pages where users can mess around with the wiki pages without messing up the real wiki page that they are working on.

How do they work?

You can copy the contents of any page you want to work on into that page and do your thing to it before putting the changes on the actual page. This can be especially useful for really long pages that you're doing major edits to, and will need to spend several days on.

How to get one?

Each user gets their own personal page in the Ubuntu wiki (after signing up for a LaunchPad account).

To create one

In the address bar, after the wiki.ubuntu.com/ part, type in <your username>/sandbox and press enter. You should get a page that says, "This page does not exist yet. You can create a new empty page, or use one of the page templates", on it. On the top of this page, under the "Ubuntu Wiki" banner, there is a button called, "Edit". This button allows you go into editting mode where you can work on the page that you need without messing up the real page. Make sure you save this page when you are done editting it!

Offline MoinMoin Wiki

You can download a copy of MoinMoin and run it in standalone mode on your computer (without serving it out on the internet) as a private wiki. You can create as many new pages as you like and paste the contents of any Ubuntu wiki page into it to make changes to it before posting them officially online.

Use the SystemInfo page to check what version the Ubuntu Community Wiki is running on.

Then follow these steps to get it and set it up:

http://paste.ubuntu.com/6116557/

NOTE: This is HTML code, so you'll want to download it into a text file and save it with an .htm or .html extension so you can open it in your browser.

NOTE: Beware that with the last two methods, someone else may make changes to the page in question while you have a copy of it in your online sandbox or in your personal wiki. You'll want to compare the current contents of the page with your contents for the page when you're ready to replace them. I highly recommend Meld for this, and it's available in the package manager.

What's next

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.