Documentation/HowTo/FirstTimers

OpenStack Documentation

Documentation Contributor Guide — HowTo for first timers — Building documentation — Speciality Teams — Documentation office hours

For OpenStack documentation, one of the best places to start is by walking through the install guide and completing it by hand. You can complete a 2-node install with two VMs, for example. Keep notes as you go, offering suggestions for improvement.

Another good first-time docs task is to go to the bugs list at https://bugs.launchpad.net/openstack-manuals/+bugs and look at the new bugs. When you see a doc bug you know how to fix, comment in the bug how to fix the bug. Mark it "Triaged" and give it a status based on the documentation bug triaging guidlines. If you're up for it, you can assign yourself the bug.

Here's a step-by-step signup tutorial:

Contributor Setup (Join in, prove you are you)

Go to http://openstack.org/join, fill out forms. Note: To avoid confusion, use the same email address everywhere. Everywhere!
On the computer where you will commit, generate SSH key: $ ssh-keygen –t rsa
Enter a password if you want -- it’s optional, but if you enter one, remember it, and you have to enter it every time you commit.
View and copy SSH key: less ~/.ssh/id_rsa.pub
Add your SSH key under "register an SSH public key"
Install git. https://help.github.com/articles/set-up-git
Configure git so it knows you:

   $ git config --global user.name "Firstname Lastname"
   $ git config --global user.email name@youremail.com

Repository Setup (Get your git on, Get files for work)

Clone a repository: $ git clone git://git.openstack.org/openstack/openstack-manuals.git
Switch to the directory: cd openstack-manuals
In the directory where the repository is cloned, install git-review so you can submit patches:

   Windows: 
       curl http://pypi.python.org/packages/source/g/git-review/git-review-1.23.tar.gz -L > git-review.tar.gz
       tar zxvf git-review.tar.gz
       cd git-review-1.23
       python setup.py install
       cd c:\source\nova
   Mac/Linux:
   $ sudo pip install git-review
   $ cd nova
   Ubuntu:
   $ sudo apt-get install git-review
   $ cd nova

Set up git review:

   Mac/Linux:
       $ git review –s 
   Windows:
       git-review

You get further instructions if you haven't created a username on review.openstack.org

Create a new remote with this command: $ git remote add gerrit ssh://<username>@review.openstack.org:29418/openstack/openstack-manuals.git
Checkout: $ git checkout master; git remote update; git pull origin master
Assign a bug to yourself. https://bugs.launchpad.net/openstack-manuals/+bug/1252931
Create a new local branch: $ git checkout -b fix-bug-1252931
Fix the bug in the docs, read the guide on How to contribute to the documentation, pay attention to on Policies and conventions section which talks about Git commit messages, backports and other conventions.
Commit the local change: $ git commit -a
Edit the commit message, following the guidelines documented at the git commit messages page.
Create a patch for review.openstack.org with: $ git review -v
Copy and paste the URL returned from git review to take a look: http://review.openstack.org/nnnnnn
Celebrate and wait for reviews

Once you've submitted a patch, it's not uncommon for people to ask for changes before approval. Here's how you do that:

Get the unique patch number from review.openstack.org, copy it
At the command line, change to the directory where the repo is stored
Enter: git review -d nnnnn (where nnnnn is pasted from the review.openstack.org/nnnnn URL)
Make your edits
In the directory where the repo is stored: $ git commit -a --amend
Then push to review.openstack.org again: $ git review -v
Wait for more reviews