Create a GitHub account at github.com. Download and install Git from http://git-scm.com/downloads Create your local repository directory $mkdir /Users/yourusername/code/ http://www.sourcetreeapp.com/download/ Ignore the Atlassian Bitbucket and Stack setup Add your GitHub username and password Set your local repository location You can download a 30 day trial of Oxygen. The floating licenses donated by OxygenXML have all been handed out.http://www.oxygenxml.com/download_oxygenxml_editor.html You can use emacs or vi editors. Here are some great resources on DocBook and Emacs' NXML mode: http://paul.frields.org/2011/02/09/xml-editing-with-emacs/ https://fedoraproject.org/wiki/How_to_use_Emacs_for_XML_editing http://infohost.nmt.edu/tcc/help/pubs/nxml/ If you prefer vi, there are ways to make DocBook editing easier: https://fedoraproject.org/wiki/Editing_DocBook_with_Vi $mkdir /usr/local/apache-maven The latest stable binary fromhttp://maven.apache.org/download.cgi into /usr/local/apache-maven Set your maven user profile settings $ export M2_HOME=/usr/local/apache-maven/apache-maven-3.0.5 $ export M2=$M2_HOME/bin $ export PATH=$M2:$PATH $ export MAVEN_OPTS='-Xms256m -XX:MaxPermSize=1024m -Xmx1024m' verify maven is setup with $ mvn --install Create a Launchpad account: Visit https://login.launchpad.net/+new_accountAfter you create this account, the follow-up page is slightly confusing. It doesn't tell you that you are done. (It gives you the opportunity to change your -password, but you do not have to.) Add at least one SSH key to your account profile. To do this, follow the instructions on https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair". Join The OpenStack Foundation: Visit https://www.openstack.org/join. Among other privileges, this also allows you to vote in elections and run for elected positions within The OpenStack Project. When signing up for the Foundation Membership, make sure to give the same E-mail address you'll use for code contributions, since the Primary Email Address in you Foundation Profile will need to match the Preferred Email you set later in your Gerrit contact information. the CLA: Every developer and contributor needs to sign the Individual Contributor License agreement. Visit https:// review.openstack.org/ and click the Sign In link at the top-right corner of the page. Log in with your Launchpad ID. You can preview the text of the Individual CLA. Add your SSH keys to your GitHub account profile (same one as used in Launchpad, they must match). When you copy and paste the SSH key, include the ssh-rsa algorithm and computer identifier. If this is your first time setting up git and Github, be sure to run these steps in a Terminal window: $git config --global user.name "Firstname Lastname" $ git config --global user.email "your_email@youremail.com" Install git-review. If pip is not already installed, use "sudo easy_install pip" to install it on a Mac or Ubuntu $sudo pip install git-review Change to the directory $cd /Users/yourusername/code Clone the openstack-manuals repository with$git clone http://github.com/openstack/openstack-manuals.git Change directory to the pulled repository $cd openstack-manuals Enter your Launchpad account information after testing for ssh key setup with $git review -s Submit a bug. Enter the summary as "Training, " with a few words. Be descriptive as possible in the description field. Open the tag pull-down and enter training-manuals.

Note: For this example, we are going to assume bug 1188522 and change 33713 Bring uphttps://bugs.launchpad.net/openstack-manuals Select a bug that is unassigned and that you can fix. Syntax errors are the best ones to start off with. Using oXygen, open the /Users/<username>/code/openstack-manuals/doc/admin-guide-cloud/bk-admin-guide-cloud.xml master page for this example. It links together the rest of the material. Find the page with the bug. Open the page that is referenced in the bug description by selecting the content in the author view. Verify you have the correct page by visually inspecting the html page and the xml page. In the shell, $cd /Users/<username>/code/openstack-manuals/doc/admin-guide-cloud/ Verify that you are on master with $git checkout master Create your working branch off master with $git checkout -b bug/1188522 Verify that you have the branch open through SourceTree Correct the bug through oXygen. Toggle back and forth through the different views at the bottom of the editor. Once the bug is fixed, verify that the documentation can be built without errors by running $mvn clean generate-sources Verify that the HTML page reflects your changes properly. You can open the file from the command line by using the "open" command $open target/docbkx/webhelp/local/openstack-training/index.html Add the changes $git add . Commit the changes $git commit -a -m "Removed reference to volume scheduler in the computer scheduler config and admin pages, bug 1188522" Submit the bug fix to Gerrit $git review Track the Gerrit review process athttps://review.openstack.org/#/c/33713. Follow and respond inline to the Code Review requests and comments. Your change will be tested, track the Jenkins testing process at https://jenkins.openstack.org If your change is rejected, complete the following steps: Respond to the inline comments if any Update the status to work in progress Checkout the patch from the Gerrit change review $git review -d 33713 Follow the recommended tweaks to the files Rerun $mvn clean generate-sources add your additional changes to the change log $git commit -a --amend Final commit $git review Update the Jenkins status to change completed Follow the jenkins build progress at https://jenkins.openstack.org/view/Openstack-manuals/. Note if the build process fails, the online documentation will not reflect your bug fix. Submit a bug. Enter the summary as "Training, " with a few words. Be descriptive as possible in the description field. Open the tag pull-down and enter training-manuals.

Bring uphttps://bugs.launchpad.net/openstack-manuals/+filebug Give your bug a descriptive name verify if asked that it is not a duplicate Add some more detail into the description field Once submitted, select the assigned to pane and select assign to me Follow the instructions for fixing a bug in the Fix a Documentation Bug section. Submit a bug. Enter the summary as "Training, " with a few words. Be descriptive as possible in the description field. Open the tag pull-down and enter training-manuals.

This section is using the submission of this training material as the example Create a bp/training-manuals branch$ git checkout -b bp/training-manuals From the openstack-manuals repository, use the template user-story-includes-template.xml as the starting point for your user story. bk001-ch003-associate-general.xml has at least one other included user story that you can use for additional help. Include the user story xml file into the bk001-ch003-associate-general.xml file. Follow the syntax of the existing xi:include statements. When your editing is completed. Double check Oxygen doesn't have any errors you are not expecting. Run maven locally to verify the build will run without errors $ mvn clean generate-sources Add your changes into git$ git add . Commit the changes with good syntax. After entering the commit command, VI syntax applies. Use "i" to insert and Esc to break out. ":wq" to write and quit.git commit -a my very short summary my more details go here. few sentences would be nice. blueprint training-manuals Submit your patch for review$ git review Once last step. Go to the review page listed after your submitted your review and add the training core team as reviewers; Sean Roberts and Colin McNamara. More details on branching can be found here under Gerrit Workflow and the Git docs Submit a bug. Enter the summary as "Training, " with a few words. Be descriptive as possible in the description field. Open the tag pull-down and enter training-manuals.

Getting Accounts and Tools: We can't do this without operators and developers using and creating the content. Anyone can contribute content. You will need the tools to get started. Go to the Getting Tools and Accounts page. Pick a Card: Once you have your tools ready to go, you can assign some work to yourself. Go to the Training Trello/KanBan storyboard and assign a card / user story from the Sprint Backlog to yourself. If you don't have a Trello account, no problem, just create one. Email seanrob@yahoo-inc.com and you will have access. Move the card from the Sprint Backlog to Doing. Create the Content: Each card / user story from the KanBan story board will be a separate chunk of content you will add to the openstack-manuals repository openstack-training sub-project. Open the file st-training-guides.xml with your XML editor. All the content starts with the set file st-training-guides.xml. The XML structure follows the hierarchy Set -> Book -> Chapter -> Section. The st-training-guides.xml file holds the set level. Notice the set file uses xi:include statements to include the books. We want to open the associate book. Open the associate book and you will see the chapter include statements. These are the chapters that make up the Associate Training Guide book. Create a branch using the card number as associate-card-XXX where XXX is the card number. Review Creating a Branch again for instructions on how to complete the branch merge. Copy the user-story-includes-template.xml to associate-card-XXX.xml. Open the bk001-ch003-asssociate-general.xml file and add <xi:include href="associate-card-XXX.xml"> Side by side, open associate-card-XXX.xml with your XML editor and open the ubuntu 12.04 install guide with your HTML browser. Find the HTML content to include. Find the XML file that matches the HTML. Include the whole page using a simple href like <xi:include href="associate-card-XXX.xml"> or include a section using xpath like <xi:include href="../basic-install/src/basic-install_controller-common.xml" xpointer="xmlns(db=http://docbook.org/ns/docbook) xpath(//*[@xml:id = 'controller-os'])"> . Review the user-story-includes-template.xml file for the whole syntax. Copy in other content sources like the Aptira content, your own text describing what needs to be learned with the section, diagrams, and quizes. If you include content from another source like Aptira cocntent make extra paragraph referencing the file and/or HTTP address the content came from. Verify the code is good by runnning mvn clean generate-sources and by reviewing the local HTML in file:///Users/(localUser)/code/openstack-manuals/doc/training-guide/target/docbkx/webhelp/local/training-guide/content/ Merge the branch Move the card from Doing to Done Submit a bug. Enter the summary as "Training, " with a few words. Be descriptive as possible in the description field. Open the tag pull-down and enter training-manuals.