Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

How to contribute to OpenStack Documentation


Published on

In this presentation from the 2013 OpenStack Documentation boot camp, you'll go from zero to merging your first patch.

Published in: Technology
  • Be the first to comment

How to contribute to OpenStack Documentation

  1. 1. How to Contribute to OpenStack Documentation Mirantis, 2013
  2. 2. • The philosophy of documentation • The documentation infrastructure • Setting up the required accounts • Installing the required software • Making a contribution Contributing to OpenStack Documentation
  3. 3. • Documentation shouldn't be an afterthought • Documentation treated like code • Automate documentation wherever possible Documentation philosophy
  4. 4. Documentation infrastructure
  5. 5. Getting ready to contribute to documentation • Becoming a member of the docs team • Configuring Launchpad • Configuring Gerrit • Working with Github • Submitting a bug • Fixing a bug
  6. 6. Becoming a team member • Go to • Join the OpenStack Foundation
  7. 7. Becoming a team member • Read the membership terms • Add your personal information • Specify affiliation
  8. 8. Configuring Launchpad: Create an account • Go to • Set up a new account • Verify your email address
  9. 9. Configuring Launchpad: Access OpenStack on Launchpad • Access OpenStack on Launchpad at • Log in to Launchpad (again)
  10. 10. Configuring Launchpad: Create an SSH key • Create an SSH key ssh-keygen -t rsa -C "” • Specify the file location • Specify a passphrase
  11. 11. Configuring Launchpad: Add the SSH key to Launchpad • Click your username • Choose to add an SSH Key
  12. 12. Configuring Launchpad: Add the SSH key to Launchpad (cont’d) • Log in again (if necessary) • Copy the public key to the clipboard • Paste into Launchpad
  13. 13. Setting up GitHub • Go to • Create an account • Add your SSH Key
  14. 14. Setting up Gerrit • Go to • Sign in • Click New Contributor Agreement • Select ICLA • Fill out the form and type “I AGREE”
  15. 15. Joining the Docs Team • Go to • Log in if necessary • Click Join Team • Click Join
  16. 16. Setting up your workspace: git • Install git sudo apt-get install git sudo yum install git • Configure git $ git config --global "First Last" $ git config --global
  17. 17. Setting up your workspace: git-review • Install Python's setuptools sudo apt-get install python-setuptools • Install pip sudo easy-install pip • Install git-review sudo pip install git-review • Add Gerrit git remote add gerrit ssh://<username> /openstack/openstack-manuals.git
  18. 18. Setting up your workspace: configure ssh • Generate a new key ssh-keygen -t rsa -C “” • Log in to and click Settings • Click SSH Public Keys • Copy and paste to the form • Click Add • Test your key ssh <username> -p 29418
  19. 19. Setting up your workspace: the docs • Create a local directory mkdir ~/openstack/documentation cd ~/openstack/documentation • Clone the repository git clone git:// openstack-manuals.git • Navigate to the openstack-manuals directory cd openstack-manuals • Confirm git-review is working git review -s
  20. 20. Setting up your workspace: tools • Install Maven sudo apt-get install maven • Pick an editor, (almost) any editor
  21. 21. Fixing a docs bug • All changes to docs must be tied to a bug • Docs bugs are listed at /+bugs?orderby=-id&start=0
  22. 22. Making a documentation change • Update your local copy git remote update git checkout master git pull origin master • Create a topic branch for the bug git checkout -b bug/1189885 • Make changes locally
  23. 23. Testing your changes • Build the book cd openstack-manuals/doc/<manual> mvn clean generate-sources • View the changes in /target/docbkx/webhelp/<guide-name> • Compare to the old version,e specially if you're not vamiliar with the book
  24. 24. Committing changes • One change per commit • Stage the commit: git commit -a • Write the commit message: Addition of chainsaw juggling documentation Added new section on the proper juggling of chainsaws within Nova. Closes-Bug: #1009973 Implements: blueprint chainsaw-juggling Change-Id: I4946a16d27f712ae2adf8441ce79e6c0bb0bb657
  25. 25. Committing changes (cont’d) • More information on commit messages:
  26. 26. Submitting the change for review • Submit the change git review • The change shows up on • Core team is notified
  27. 27. Documentation workflow • File/claim a bug • Check the documentation project our of git • Make changes locally • Build the documentation locally • Test the documentation • Submit for review • Merge changes