|
|
| (122 intermediate revisions by 9 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}} |
| − |
| |
| − | == 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/HowTo#Doc_Bug_Triaging_Guidelines|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!<br />
| |
| − |
| |
| − | 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.<br />
| |
| − |
| |
| − | 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. See https://review.openstack.org/#/settings/ssh-keys.<br />
| |
| − |
| |
| − | Install git. See https://help.github.com/articles/set-up-git.<br />
| |
| − |
| |
| − | 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) ===
| |
| − |
| |
| − | '''Note''': For Windows, you must install pre-requisites: git (http://msysgit.github.io/), curl (http://curl.haxx.se/), tar or 7-zip, and a working Python 2.7 environment.
| |
| − |
| |
| − | 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
| |
| − |
| |
| − | 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 ===
| |
| − | # 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
| |
| − | # 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 on [[Documentation/HowTo#Policies_and_conventions|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 [[GitCommitMessages|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
| |
| − |
| |
| − | === 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:
| |
| − |
| |
| − | # 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
| |
| | | | |
| | ---- | | ---- |
| | [[Category:Documentation]] | | [[Category:Documentation]] |
