how to contribute to openstack documentation

How to Contribute to OpenStack Documentation

Mirantis, 2013

• The philosophy of documentation

• The documentation infrastructure

• Setting up the required accounts

• Installing the required software

• Making a contribution

Contributing to OpenStack Documentation

• Documentation shouldn't be an afterthought

• Documentation treated like code

• Automate documentation wherever possible

Documentation philosophy

Documentation infrastructure

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

Becoming a team member

• Go to https://www.openstack.org/join/

• Join the OpenStack Foundation

Becoming a team member

• Read the membership terms

• Add your personal information

• Specify affiliation

Configuring Launchpad: Create an account

• Go to https://login.launchpad.net/+new_account

• Set up a new account

• Verify your email address

Configuring Launchpad: Access OpenStack on Launchpad

• Access OpenStack on Launchpad at https://launchpad.net/openstack

• Log in to Launchpad (again)

Configuring Launchpad: Create an SSH key

• Create an SSH keyssh-keygen -t rsa -C "your_email@example.com”

• Specify the file location

• Specify a passphrase

Configuring Launchpad: Add the SSH key to Launchpad

• Click your username

• Choose to add an SSH Key

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

Setting up GitHub

• Go to http://github.com

• Create an account

• Add your SSH Key

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”

Joining the Docs Team

• Go to http://launchpad.net/openstack-manuals

• Log in if necessary

• Click Join Team

• Click Join

Setting up your workspace: git

• Install gitsudo 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

Setting up your workspace: git-review

• Install Python's setuptoolssudo apt-get install python-setuptools

• Install pipsudo easy-install pip

• Install git-reviewsudo pip install git-review

• Add Gerritgit remote add gerrit \ ssh://<username>@review.openstack.org:29418\ /openstack/openstack-manuals.git

Setting up your workspace: configure ssh

• Generate a new keyssh-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 keyssh <username>@review.openstack.org -p 29418

Setting up your workspace: the docs

• Create a local directorymkdir ~/openstack/documentation

cd ~/openstack/documentation

• Clone the repositorygit clone git://git.openstack.org/openstack/ \ openstack-manuals.git

• Navigate to the openstack-manuals directorycd openstack-manuals

• Confirm git-review is workinggit review -s

Setting up your workspace: tools

• Install Mavensudo apt-get install maven

• Pick an editor, (almost) any editor

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

Making a documentation change• Update your local copy

git remote update

git checkout master

git pull origin master

• Create a topic branch for the buggit checkout -b bug/1189885

• Make changes locally

Testing your changes

• Build the bookcd 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

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

Committing changes (cont’d)

• More information on commit messages:https://wiki.openstack.org/wiki/GitCommitMessages

Submitting the change for review

• Submit the changegit review

• The change shows up on http://review.openstack.org

• Core team is notified

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