Jump to: navigation, search

Documentation/HowTo/FirstTimers

< Documentation‎ | HowTo
Revision as of 16:31, 4 July 2014 by Dfleming (talk | contribs) (Contributor Setup (Join in, prove you are you))

How can I help?

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.

Step-by-step 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 an SSH key:

 $ ssh-keygen –t rsa 
Note: On Windows, you must install git for Windows (http://msysgit.github.io/), and then run ssh-keygen from gitbash.

Enter a password if you want -- it’s optional, but if you enter one, remember it: You must enter it every time you commit. View and copy SSH key:

 $ less ~/.ssh/id_rsa.pub

Add your SSH key. See https://review.openstack.org/#/settings/ssh-keys. 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 review on)

  Windows: (Pre-requisites are git (http://msysgit.github.io/), curl (http://curl.haxx.se/), tar or 7-zip, and a working Python 2.7 environment)
       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
      
   Mac/Linux:
       $ sudo pip install git-review
  
   Ubuntu:
       $ sudo apt-get install git-review
  
  • Set up git review:
   Mac/Linux:
        $ git review –s 
   Windows:
        git-review 
  • Create a new remote with this command, you should be able to copy/paste it from the returned information at the command line:
$ git remote add gerrit ssh://<username>@review.openstack.org:29418/openstack/openstack-manuals.git

Work locally

  1. In the repo directory, checkout the master branch and make sure it hasn't changed by pulling updates locally: $ git checkout master; git remote update; git pull origin master
  2. Assign a bug to yourself, such as. https://bugs.launchpad.net/openstack-manuals/+bug/1252931
  3. Create a new local branch, based on master. You don't have to name it with the bug number but it's helpful: $ git checkout -b fix-bug-1252931
  4. 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.
  5. Commit the local change: $ git commit -a
  6. Edit the commit message, following the guidelines documented at the git commit messages page.
  7. Create a patch for review.openstack.org with: $ git review -v
  8. Copy and paste the URL returned from git review to take a look: http://review.openstack.org/nnnnnn
  9. Celebrate and wait for reviews

Troubleshoot git review

The first time you run git review or git-review, you may see:

   The authenticity of host '[review.openstack.org]:29418 ([198.101.231.251]:29418) can't be established.

Please answer that you'd like to continue to connect by typing "yes" (all three letters) at the prompt.

When connecting to gerrit for the first time, you see:

   Could not connect to gerrit.
   Enter your gerrit username: 

You must enter the username that matches what is in review.openstack.org in Settings.

If your network connection to the outside world is weak, wonky, or otherwise somewhat disconnected, you may see:

   Read from socket failed: Connection reset by peer

Please just try again when your network connection is acting better.

If you see this:

   fatal: Not a git repository (or any of the parent directories): .git

It means that you are not in a directory that is a git repository. It looked for a .git file but didn't find one, and has no further instructions, so it's considered fatal. Just switch to the repository's directory with the cd command and re-run the command that gave you the fatal error. It'll be okay.

If you see this:

   /usr/bin/env: python: No such file or directory

It means your Python environment is not set up correctly. Please refer to the Python documentation for your operating system to sort this error out.

Respond to requests

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

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