Getting started with OpenStack documentation

OpenStack documentation is developed the same way as the code, so if you’re already an OpenStack ATC then you have the skills required. If this is your first contribution, the good news is that once you have these skills you can then use them to commit to other parts of OpenStack as well.

Important things you should know before you start:

• These steps have more detail on the wiki: http://bit.ly/1YKUMGH
• The docs team happily answers questions on IRC (#openstack-doc) or our mailing list: http://bit.ly/1YKUMGH.
• Most of our end-user docs are written in RST, but some are still in Docbook XML. View conventions for both languages on the wiki: http://bit.ly/1iG5lK4
• Jump in and push patches. The documentation review system means that you will not break anything, and it’s a good way to learn the ropes.

To start you’ll need a few things, but you only need to go through these steps once. These instructions assume you are using Ubuntu; you can find instructions for other operating systems here: https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers#Set_up_for_contribution

• Set up a Launchpad account (http://bit.ly/1NYcnpv). You’ll also need to join the OpenStack Foundation, as a Foundation member, and sign the individual contributor agreement (http://www.openstack.org/join).
• Install git, git-review, and tox. Git is a version control system, and the place where all the code for OpenStack lives. Tox tests code before you upload it, and git-review interacts with Gerrit:

$ sudo apt-get install git

$ sudo pip install tox git-review

• Create an SSH key with this command (you can hit enter to accept the default values):

$ ssh-keygen -t rsa

Then upload your new key to your Gerrit profile at http://bit.ly/1KGxlXV

• Configure your git user information:

$ git config –global user.name "Firstname Lastname"

$ git config –global user.email [email protected]

$ git config –global gitreview.username yourgerritusername

• Download a local copy of the openstack-manuals repository (this can take a while):

$ git clone http://bit.ly/1Gdj8xv

• Change into the openstack-manuals directory, add a new git remote, and set up git-review:

$ cd ~/openstack-manuals

$ git remote add gerrit ssh://<username>@review.openstack.org:29418/openstack/openstack-manuals.git

$ git review -s

You’re ready to contribute!

To start, we’ll fix an imaginary typo, "you can provision you’re own resources", on this page: http://bit.ly/1jrHa2L

• Create a git branch to work in, and call it something appropriate. When working on a bug use the bug number. In this case, we’ll use ‘userguide_typofix’:

$ git checkout -b userguide_typofix

• Find the source file containing the typo by looking at the URL. In this case, we want the “user-guide” book, and the “intro-user” file:

$ cd ~/openstack-manuals/doc/user-guide/source/

$ gedit intro-user.rst

• Make your change, then save the file.
• Test the change with tox:

$ cd ~/openstack-manuals

$ tox

• Commit the change:

$ git commit -a

This opens an editor for your commit message, which must conform to certain standards. In this example a simple message will do:

Fixed typo

Changed the word "you’re" to "your".

Note that there is a blank line between the title and the description. For more information on writing commit messages see: http://bit.ly/1BBEhAe

• Save your commit message and close the editor.
• Push your patch to gerrit for review:

$ git review

The command outputs a link to the review in Gerrit, for example: https://review.openstack.org/#/c/123456/

Congratulations, your first patch is complete! After some automated testing by Jenkins, the documentation team reviews your patch and either approves it or suggests improvements. It’s normal for a patch to go through several review rounds before it’s accepted. If you need to make further changes to your patch, follow these instructions: http://bit.ly/1NYcxNN.

You need at least one +1 on your patch, and at least two +2s from core docs team members before it can be merged. But after that’s done, you’re an ATC!

Now that your environment is set up, future contributions are easy.

• Find a bug to work on. Docs bugs tagged as ‘low-hanging fruit’ are a good place to start: http://bit.ly/1FE24Wp.
• Update your local repository:

$ cd ~/openstack-manuals

$ git remote update

$ git checkout master

$ git pull –ff-only origin master

• Create a new branch:

$ git checkout -b branchname

• Make your fix then commit it just like before:

$ git commit -a

$ git review

Welcome to the docs team 🙂

Get involved!
The docs team is always looking for technical writers, developers (even those who don’t think they’re good writers.)
Join the OpenStack Docs mailing list.
Participate in the weekly meetings: held on #openstack-meeting every Wednesday at alternating times for different time zones:
APAC: Wednesday, 00:30:00 UTC #openstack-meeting
US: Wednesday, 14:00:00 UTC