From 9cb73bf92a59f70e94000d9a2caeaea063e5755e Mon Sep 17 00:00:00 2001 From: Shilla Saebi Date: Mon, 24 Feb 2014 00:41:20 -0500 Subject: [PATCH] cleanup of operator-editing-code added commas and joined sentences corrected sentence formats capitalized before sentence removed capitals that were extra in sentence changed para tag location reomved "show" per comments capitalized a in Agreement Change-Id: I30c5c5a02af58141359fb7634dbf82d9c18e2181 --- operator-editing-code.xml | 990 +++++++++++++++++++++----------------- 1 file changed, 549 insertions(+), 441 deletions(-) diff --git a/operator-editing-code.xml b/operator-editing-code.xml index 461ba25c..3a6845ae 100644 --- a/operator-editing-code.xml +++ b/operator-editing-code.xml @@ -1,480 +1,588 @@
Editing Code
Get Tools and Accounts - - - - First create a GitHub account at github.com. - - Check out https://wiki.openstack.org/wiki/Documentation/HowTo for more extensive setup instructions - - Download and install Git from http://git-scm.com/downloads - - - Create your local repository directory - $ mkdir /Users/username/code/ - - - Install SourceTree - - - http://www.sourcetreeapp.com/download/ - - - Ignore the Atlassian Bitbucket and Stack - setup - - - Add your GitHub username and password - - - Set your local repository location - - - - - Install an XML editor - - - You can download a 30 day trial of Oxygen. The floating licenses donated by OxygenXML have all been handed out. + + First create a GitHub account at github.com. + + + Check out https://wiki.openstack.org/wiki/Documentation/HowTo + for more extensive setup instructions + + + Download and install Git from http://git-scm.com/downloads + + + Create your local repository directory + $ mkdir /Users/username/code/ + + + Install SourceTree + + + http://www.sourcetreeapp.com/download/ + + + Ignore the Atlassian Bitbucket and Stack + setup + + + Add your GitHub username and + password + + + Set your local repository + location + + + + + Install an XML editor + + + 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 - - AND/OR PyCharm http://download.jetbrains.com/python/pycharm-community-3.0.1.dmg - AND/OR 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 - - - - - Install Maven - - - Create the apache-maven directory - $ sudo mkdir /usr/local/apache-maven + + + AND/OR PyCharm http://download.jetbrains.com/python/pycharm-community-3.0.1.dmg + + + AND/OR 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 + + + + + + + Install Maven + + + Create the + apache-maven + directory + $ sudo mkdir /usr/local/apache-maven - - - Copy the latest stable binary from + + Copy the latest stable binary from http://maven.apache.org/download.cgi into + >http://maven.apache.org/download.cgi + into /usr/local/apache-maven. - - - Install maven with - $ sudo /usr/local/apache-maven/XXXXX - - - - Add the maven path - $ sudo touch /etc/path.d/mvn.path + + + Install maven: + $ sudo /usr/local/apache-maven/XXXXX + + + Add the maven path: + $ sudo touch /etc/path.d/mvn.path $ sudo vi /etc/path.d/mvn.path $ /usr/local/apache-maven/apache-maven-3.0.5/bin - - - Set your maven user profile settings - $ export MAVEN_OPTS='-Xms256m -XX:MaxPermSize=1024m -Xmx1024m' - - - Verify that maven is setup with - $ sudo 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 + + + Define your maven user profile + settings: + $ export MAVEN_OPTS='-Xms256m -XX:MaxPermSize=1024m -Xmx1024m' + + + Verify that maven is set up + correctly: + $ sudo mvn --install + + + + + + Create a Launchpad account: Visit + https://login.launchpad.net/+new_account. + After you create this account, the follow-up page + is slightly confusing. It does not 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. - - - Validate your gerrit identity: - Add your public key to your gerrit identity by going to - https://review.openstack.org, - click the Sign In link, if you are not already logged in. At the top-right corner - of the page select settings, pick your username, then add your public ssh key under - "SSH Public Keys". - Also every developer and contributor needs to sign the - Individual Contributor License agreement (CLA). Review the agreement - under "Agreements", and sign to continue. - - - 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/username/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 - - - + + + Join The OpenStack Foundation: Visit https://www.openstack.org/join. Among + other privileges, this membership enables you to + vote in elections and run for elected positions in + The OpenStack Project. When you sign up for + membership, make sure to give the same e-mail + address you will use for code contributions + because the primary e-mail address in your + foundation profile must match the preferred e-mail + that you set later in your Gerrit contact + information. + + + Validate your Gerrit identity: Add your public + key to your gerrit identity by going to https://review.openstack.org, click + the Sign In link, if you + are not already logged in. At the top-right corner + of the page select settings, then add your public + ssh key under SSH Public + Keys. + 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 + (the same one that was used in Launchpad). 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/username/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 + +
Fix a Documentation Bug - - - - Note: For this example, we are going to assume bug - 1188522 and change 33713 - - - Bring up + + Note: For this example, we are going to assume + bug 1188522 and change 33713 + + + Bring up https://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 at + + 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. - - - + >https://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 Documentation Bug Fix - - - - Bring up + + Bring up https://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" or "sarob" - - - Follow the instructions for fixing a bug in the Fix a - Documentation Bug section. - - - + + + 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" or "sarob" + + + Follow the instructions for fixing a bug in the + Fix a Documentation Bug section. + +
Create a Branch - - 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. File - bk001-ch003-associate-general.xml + + This section uses 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. File + 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 + 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 complete, double check + Oxygen doesn't have any unexpected errors. + + + 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 very short summary +more details go here. A few sentences would be nice. -my more details go here. few sentences would be nice. - -blueprint training-manuals - - - Submit your patch for review$ git review - - - One last step. Go to the review page listed after you 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 - - +blueprint training-manuals + + + Submit your patch for + review$ git review + + + The last step is to go to the review page listed + after you 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 + +
Add Content to the 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 Accounts and + Tools: We cannot 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 + >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 do not 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 by 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 quizzes. - 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/username/code/openstack-manuals/doc/training-guide/target/docbkx/webhelp/local/training-guide/content/. - - - - Merge the branch. - - - Move the card from Doing to Done. - - - + + + 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 including the + Aptira content, a description of what the section + aims to teach, diagrams, and quizzes. If you + include content from another source like Aptira + content, add a paragraph that references the file + and/or HTTP address from where the content + came. + + + Verify the code is good by running mvn + clean generate-sources and by + reviewing the local HTML in file:///Users/username/code/openstack-manuals/doc/training-guide/target/docbkx/webhelp/local/training-guide/content/. + + + Merge the branch. + + + Move the card from Doing to Done. + +