Jump to: navigation, search

Difference between revisions of "Documentation/HowTo/FirstTimers"

(Step-by-step tutorial)
m (First timer documentation contributor link outdated, updated to new url)
 
(8 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 +
Read the new content in the [http://docs.openstack.org/contributor-guide/quickstart/first-timers.html Documentation Contributor Guide].
 
{{OpenStack_Documentation_Navbar}}
 
{{OpenStack_Documentation_Navbar}}
 
== 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 or https://bugs.launchpad.net/openstack-api-site/+bugs and look at the new bugs. When you see a doc bug you know how to fix or can confirm it's really a doc bug, give it a status based on the [[Documentation/HowTo#Doc_Bug_Triaging_Guidelines|documentation bug triaging guidelines]]. If you're up for it, you can assign yourself the bug after it has been confirmed or reported by one other person.
 
 
=== Set up for contribution ===
 
To get started, complete the following steps:
 
 
# '''Create a''' [https://login.launchpad.net/+login Launchpad account] (through UbuntuOne).
 
# '''Join the Launchpad''' [https://launchpad.net/~openstack-doc-bugs OpenStack Documentation Bug Team]
 
# '''Join the OpenStack Foundation''' at http://www.openstack.org/join (to see if you joined already, go to http://www.openstack.org/profile) 
 
# '''Sign the Contributor License Agreement''' (this is part of joining the Foundation above)
 
# '''Setup git review''' and get familiar with the [http://docs.openstack.org/infra/manual/developers.html#development-workflow Development Workflow]
 
 
For further details and reference on setting up your environment, see the [http://docs.openstack.org/infra/manual/developers.html#getting-started Getting Started] section of the Infrastructure Manual.
 
 
=== Install 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 your text editor ===
 
To help keeping the documents clean and easy to compare, all OpenStack projects and the Documentation team require that text is wrapped at [https://www.python.org/dev/peps/pep-0008/#maximum-line-length 79 characters maximum], with no white spaces at the end of the line. It helps to configure the text editor to do that automatically.
 
 
For example, in .vimrc:
 
<pre><nowiki>
 
set list
 
set listchars=tab:>-,trail:-,extends:#,nbsp:-
 
set modeline
 
set tw=78
 
set tabstop=8 expandtab shiftwidth=4 softtabstop=4
 
</nowiki></pre>
 
 
=== Set up git and git review ===
 
====All platforms====
 
Install git. See https://help.github.com/articles/set-up-git.
 
'''Note''': If you installed Windows prerequisites, you already installed git.<br />
 
 
Configure git and git review so that they know you:
 
<pre><nowiki>
 
$ git config --global user.name "Firstname Lastname"
 
$ git config --global user.email name@youremail.com
 
$ git config --global gitreview.username yourgerritusername
 
</nowiki></pre>
 
 
If you don't remember your Gerrit user name, go to the [https://review.openstack.org/#/settings/ 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====
 
<pre><nowiki>
 
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
 
</nowiki></pre>
 
 
====Mac/Linux====
 
<pre><nowiki>
 
$ sudo pip install git-review
 
</nowiki></pre>
 
 
====Ubuntu====
 
<pre><nowiki>
 
$ sudo apt-get install git-review
 
</nowiki></pre>
 
 
=== 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.<br />
 
 
View and copy your SSH key:
 
  $ less ~/.ssh/id_rsa.pub
 
 
Add your SSH key by logging into Gerrit and viewing https://review.openstack.org/#/settings/ssh-keys.<br />
 
 
=== Set up repositories and work locally ===
 
 
'''Note:''' Documentation is in openstack/openstack-manuals mostly, so this walkthrough uses that repo as the example. You can also substitute openstack/api-site, openstack/operations-guide, openstack/security-guide, or openstack/training-guides, or openstack/ha-guide in the steps below.
 
 
Clone a repository. For example, clone openstack/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
 
 
See [[Documentation/HowTo/FirstTimers#Troubleshoot your setup|Troubleshoot your setup]] if you have any difficulty with this step.
 
 
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 [[Documentation/HowTo|How to contribute to the documentation]], pay attention to the [[Documentation/HowTo#Policies_and_conventions|Policies and conventions]] section, which describes Git commit messages, back port procedures, and other conventions.
 
 
Commit the local change:
 
  $ git commit -a
 
 
Edit the commit message, following the guidelines documented at the [[GitCommitMessages|git commit messages page]].
 
 
The first time you set up a git remote named "gerrit" and try to create a patch for review.openstack.org you may see this message:
 
 
<pre>
 
<nowiki>! [remote rejected] HEAD -> refs/publish/master/addopenstackdocstheme (missing Change-Id in commit message footer)</nowiki>
 
</pre>
 
 
When this happens, run git commit -a --amend, then save the commit message again and run git review -v again.
 
 
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 ===
 
 
====Authenticity error====
 
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.
 
 
====Gerrit connection error====
 
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'''.
 
 
====Not a git repository error====
 
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.
 
 
====Gerrit location unknown error====
 
If you see this error:
 
  We don't know where your gerrit is. Please manually create a remote named "gerrit" and try again.
 
You need to make a git remote that maps to the review.openstack.org ssh port for your repo. For an example for a username annegentle and the openstack-manuals repo, you'd run this command:
 
  git remote add gerrit ssh://annegentle@review.openstack.org:29418/openstack/openstack-manuals.git
 
 
====Remote rejected error====
 
If you see this error:
 
  ! [remote rejected] HEAD -> refs/publish/master/addopenstackdocstheme (missing Change-Id in commit message footer)
 
 
The first time you set up a gerrit remote and try to create a patch for review.openstack.org you may see this message because the tool needs one more edit of your commit message in order to automatically insert the Change-Id. When this happens, run git commit -a --amend, then save the commit message again and run git review -v again.
 
 
====Permission denied error====
 
If you see this error:
 
  Permission denied (publickey).
 
 
Double and triple-check the Settings page on http://review.openstack.org to make sure your publickey on the computer (or virtual server) has been copied to SSH Public Keys on https://review.openstack.org/#/settings/ssh-keys. If you have adjusted your .ssh configuration at all your system may not be connecting using the correct key for Gerrit. List your local public key on Mac or Linux with: less ~/.ssh/id_rsa.pub. On Windows, also look for it in the same location.
 
 
=== 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.
 
 
====Accessing Gerrit over  HTTP/HTTPS====
 
If you suspect that ssh over non-standards ports might be blocked (or need to access the web using http/https) then you can configure git-review to use an http endpoint instead of ssh. Keep in mind that you will need to generate an HTTP password in gerrit at [https://review.openstack.org/#/settings/http-password https://review.openstack.org/#/settings/http-password] to use this connection. To configure git, execute the following commands:
 
    git config --global gitreview.scheme https
 
    git config --global gitreview.port 443
 
 
Then, remove the failing gerrit remote with the following command:
 
    git remote rm gerrit
 
 
And re-launch git review as follows:
 
    git review -s
 
 
And refer to the steps above to check your credentials, etc. Keep in mind that you will be prompted for your username and password (this is the HTTP password from gerrit). There will be a screen printout showing how to permanently configure your username as part of git config.
 
 
=== 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.
 
 
=== i18n ===
 
If you see this error:
 
$ git review -s
 
Problems encountered installing commit-msg hook
 
The following command failed with exit code 1
 
    "scp  :hooks/commit-msg .git/hooks/commit-msg"
 
-----------------------
 
.git/hooks/commit-msg: No such file or directory
 
-----------------------
 
You may have a LANGUAGE variable setup to something else than C. So instead, try using:
 
$ LANG=C LANGUAGE=C git review -s
 
  
 
----
 
----
 
[[Category:Documentation]]
 
[[Category:Documentation]]

Latest revision as of 01:01, 7 July 2016

Read the new content in the Documentation Contributor Guide.