How to contribute to OpenStack Documentation

2,336 views
2,050 views

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
0 Comments
3 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
2,336
On SlideShare
0
From Embeds
0
Number of Embeds
599
Actions
Shares
0
Downloads
56
Comments
0
Likes
3
Embeds 0
No embeds

No notes for slide

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 https://www.openstack.org/join/ • 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 https://login.launchpad.net/+new_account • Set up a new account • Verify your email address
  9. 9. Configuring Launchpad: Access OpenStack on Launchpad • Access OpenStack on Launchpad at https://launchpad.net/openstack • Log in to Launchpad (again)
  10. 10. Configuring Launchpad: Create an SSH key • Create an SSH key ssh-keygen -t rsa -C "your_email@example.com” • 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 http://github.com • Create an account • Add your SSH Key
  14. 14. Setting up Gerrit • Go to https://review.openstack.org • Sign in • Click New Contributor Agreement • Select ICLA • Fill out the form and type “I AGREE”
  15. 15. Joining the Docs Team • Go to http://launchpad.net/openstack-manuals • 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 user.name "First Last" $ git config --global user.email username@example.com
  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>@review.openstack.org:29418 /openstack/openstack-manuals.git
  18. 18. Setting up your workspace: configure ssh • Generate a new key ssh-keygen -t rsa -C “your_email@example.com” • Log in to review.openstack.org and click Settings • Click SSH Public Keys • Copy and paste id_rsa.pub to the form • Click Add • Test your key ssh <username>@review.openstack.org -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://git.openstack.org/openstack/ 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 https://bugs.launchpad.net/openstack-manuals /+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: https://wiki.openstack.org/wiki/GitCommitMessages
  26. 26. Submitting the change for review • Submit the change git review • The change shows up on http://review.openstack.org • 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

×