Jump to: navigation, search

Documentation/HowTo/FirstTimers

< Documentation‎ | HowTo
Revision as of 22:36, 11 December 2013 by Miranda (talk | contribs) (add step to also "add SSH key to GitHub")

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 Documentation/HowTo#Doc_Bug_Triaging_Guidelines. If you're up for it, you can assign yourself the bug.

Here's a step-by-step signup tutorial:

  1. Create an account in Launchpad at https://login.launchpad.net/+new_account
  2. Log in to your Launchpad account
  3. Generate SSH key: ssh-keygen –t rsa
  4. View and copy SSH key: less ~/.ssh/id_rsa.pub
  5. Add SSH key to Launchpad (click your name in upper right hand corner, then click ! Next to SSH keys)
  6. Go to http://openstack.org/join, fill out forms
  7. Go to http://review.openstack.org/, click Sign In, use your Launchpad account credentials
  8. Install git. https://help.github.com/articles/set-up-git
  9. If this is your first time setting up git, don't forget to add your SSH key (the same one generated before) to GitHub, and be sure to run these steps:
  10. $ git config --global user.name "Firstname Lastname"
  11. $ git config --global user.email name@youremail.com
  12. Clone a repository: $ git clone git://git.openstack.org/openstack/openstack-manuals.git
  13. Install git-review so you can submit patches: $ sudo pip install git-review or $sudo apt-get install git-review
  14. Test to ensure you can connect: $ git review –s
  15. Create a new remote with this command: $ git remote add gerrit ssh://<username>@review.openstack.org:29418/openstack/openstack-manuals.git
  16. Switch to the repository and checkout: $ git checkout master; git remote update; git pull origin master
  17. Assign a bug to yourself. https://bugs.launchpad.net/openstack-manuals/+bug/1252931
  18. Create a new local branch: $ git checkout –b fix-bug-1252931
  19. Fix the bug in the docs.
  20. Commit the local change: $ git commit -a
  21. Edit the commit message, following the guidelines documented at https://wiki.openstack.org/wiki/GitCommitMessages
  22. Create a patch for review.openstack.org with: $ git review -v
  23. Copy and paste the URL returned from git review to take a look: http://review.openstack.org/nnnnnn
  24. Celebrate and wait for reviews

Once you've submitted a patch, here's a review tutorial:

  1. Get the six-digit 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 nnnnnn (where nnnnnn is pasted from the review.openstack.org 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