Jump to: navigation, search

Difference between revisions of "Documentation/HowTo/FirstTimers"

(Windows prerequisites)
Line 12: Line 12:
  
 
Go to http://openstack.org/join. Fill out forms. '''Note''': To avoid confusion, use the same email address everywhere. Everywhere!<br />
 
Go to http://openstack.org/join. Fill out forms. '''Note''': To avoid confusion, use the same email address everywhere. Everywhere!<br />
 
=== Windows prerequisites ===
 
 
If you plan to use Windows to contribute to OpenStack, install these prerequisites:
 
* git (http://msysgit.github.io/)
 
* curl (http://curl.haxx.se/)
 
* tar (http://gnuwin32.sourceforge.net/packages/gtar.htm) or 7-zip (http://sourceforge.net/projects/sevenzip/?source=recommended)
 
* a working Python 2.7 environment (http://docs.python-guide.org/en/latest/starting/install/win/). '''Note''': As part of the Python installation, be sure to install setuptools and pip as instructed.<br /><br />
 
 
In the subsequent procedures, run commands from the gitbash command line.
 
  
 
=== Set up git and git review ===
 
=== Set up git and git review ===

Revision as of 16:02, 6 July 2014

Step-by-step tutorial

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.

Create a Launchpad account

Create a Launchpad account so that the Web interface for the Gerrit Code Review system can identify you. This account is also used to credit you with bug fixes when you make code or documentation commits.

Join the OpenStack foundation

Go to http://openstack.org/join. Fill out forms. Note: To avoid confusion, use the same email address everywhere. Everywhere!

Set up git and git review

Install git. See https://help.github.com/articles/set-up-git.

Configure git and git review so that they know you:

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

If you don't remember your Gerrit user name, go to the settings page on gerrit to check it out (it's not your email address).

On your system, install git-review so that you can submit patches:

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

Set up ssh

On the computer where you will commit, generate an SSH key:

 $ ssh-keygen –t rsa 

Optionally, enter a password. If you enter one, remember it: You must enter it every time you commit.

View and copy your SSH key:

 $ less ~/.ssh/id_rsa.pub

Add your SSH key. See https://review.openstack.org/#/settings/ssh-keys.

Set up repositories and work locally

Clone a repository. For example, clone openstack-manuals:

 $ git clone git://git.openstack.org/openstack/openstack-manuals.git

Change into the directory:

 $ cd openstack-manuals

In the same directory, set up git review:

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

Set up a remote so you can submit reviews:

 $ git remote add gerrit ssh://<username>@review.openstack.org:29418/openstack/openstack-manuals.git

In the directory for the cloned repository, check out the master branch and make sure it hasn't changed by pulling updates locally:

 $ git checkout master; git remote update; git pull origin master

Assign a bug to yourself, such as. https://bugs.launchpad.net/openstack-manuals/+bug/1252931

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

Fix the bug in the docs. Read the guide on How to contribute to the documentation, pay attention to thePolicies 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.

Respond to requests

After you submit a patch, reviewers might ask you to make changes before they approve the patch.

To submit changes to your patch, copy the unique patch number from review.openstack.org. For example, copy nnnnn from the following URL:

 https://review.openstack.org/#/c/nnnnn/

At the command line, change into your local copy of the repository. For example:

 $ cd openstack-manuals

To check out the patch, enter:

 $ git review -d nnnnn 

Where nnnnn is the review number that you copied from review.openstack.org.

Make your edits.

In your local copy of the repository:

 $ git commit -a --amend

Then push to review.openstack.org again:

 $ git review -v

Wait for more reviews.

Troubleshoot your setup

git and git review

The first time that you run git review, you might see this error:

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

Type yes (all three letters) at the prompt.

When you connect to gerrit for the first time, you might see this error:

   Could not connect to gerrit.
   Enter your gerrit username: 

Enter the user name that matches the user name in review.openstack.org in Settings.

If you see this error:

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

You are not in a directory that is a git repository: A .git file was not found.

Change into your local copy of the repository and re-run the command.

network

If your network connection is weak, you might see this error:

   Read from socket failed: Connection reset by peer

Try again when your network connection improves.

python

If you see this this error:

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

Your Python environment is not set up correctly. See the Python documentation for your operating system.