|
|
(3 intermediate revisions by one other user 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:
| |
− |
| |
− | # '''Follow infrastructure instructions to''' [http://docs.openstack.org/infra/manual/developers.html#account-setup create a Launchpad account, join the OpenStack Foundation and agree to the Individual Contributor License Agreement]
| |
− | # '''Join the Launchpad''' [https://launchpad.net/~openstack-doc-bugs OpenStack Documentation Bug Team]
| |
− | # '''Setup git review''' as described below 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 as explained in the [http://docs.openstack.org/infra/manual/developers.html#accessing-gerrit-over-https Infra Manual].
| |
− |
| |
− | === 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]] |