openstack/openstack-manuals
Code Issues Proposed changes
Files
429a8596b47486a928b8c15da990981ec13b31cb
openstack-manuals/doc/training-guide/operator-editing-code.xml
dhubbard dfdcdcb374 training, add submit a bug URL to footer of editing code pages 
Implements bug/123304

Change-Id: I5e2300714298420e2627716d8838caebf8b5718c
2013-09-30 11:22:10 -07:00

466 lines
27 KiB
XML
Raw Blame History

<?xml version="1.0" encoding="utf-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="operator-editing-code">
<title>Editing Code</title>
<section xml:id="getting-tools-and-accounts">
<title>Get Tools and Accounts</title>
<para>
<procedure>
<note>
<para>Create a GitHub account at <link xlink:href="http://github.com">github.com.</link></para>
</note>
<step>
<para>Download and install Git from <link
xlink:href="http://git-scm.com/downloads">http://git-scm.com/downloads</link></para>
</step>
<step>
<para>Create your local repository directory</para>
<screen><prompt>$</prompt><userinput>mkdir /Users/yourusername/code/</userinput></screen>
</step>
<step>
<title>Install SourceTree</title>
<substeps>
<step>
<para><link xlink:href="http://www.sourcetreeapp.com/download/">http://www.sourcetreeapp.com/download/</link></para>
</step>
<step>
<para>Ignore the Atlassian Bitbucket and Stack
setup</para>
</step>
<step>
<para>Add your GitHub username and password</para>
</step>
<step>
<para>Set your local repository location</para>
</step>
</substeps>
</step>
<step>
<title>Install an XML editor</title>
<substeps>
<step>
<para>You can download a 30 day trial of Oxygen. The floating licenses donated by OxygenXML have all been handed out.<link
xlink:href="http://www.oxygenxml.com/download_oxygenxml_editor.html"
>http://www.oxygenxml.com/download_oxygenxml_editor.html</link></para>
<para>You can use emacs or vi editors.</para>
<para>Here are some great resources on DocBook and Emacs' NXML mode:</para>
<itemizedlist><listitem><para><link xlink:href="http://paul.frields.org/2011/02/09/xml-editing-with-emacs/">http://paul.frields.org/2011/02/09/xml-editing-with-emacs/</link></para></listitem>
<listitem><para><link xlink:href="https://fedoraproject.org/wiki/How_to_use_Emacs_for_XML_editing">https://fedoraproject.org/wiki/How_to_use_Emacs_for_XML_editing</link></para></listitem>
<listitem><para><link xlink:href="http://infohost.nmt.edu/tcc/help/pubs/nxml/">http://infohost.nmt.edu/tcc/help/pubs/nxml/</link></para></listitem></itemizedlist>
<para>If you prefer vi, there are ways to make DocBook editing easier:</para>
<itemizedlist><listitem><para><link xlink:href="https://fedoraproject.org/wiki/Editing_DocBook_with_Vi">https://fedoraproject.org/wiki/Editing_DocBook_with_Vi</link></para></listitem></itemizedlist>
</step>
</substeps>
</step>
<step>
<title>Install Maven</title>
<substeps>
<step>
<screen><prompt>$</prompt><userinput>mkdir /usr/local/apache-maven</userinput></screen>
</step>
<step>
<para>The latest stable binary from<link
xlink:href="http://maven.apache.org/download.cgi"
>http://maven.apache.org/download.cgi</link> into
/usr/local/apache-maven</para>
</step>
<step>
<para>Set your maven user profile settings</para>
<screen><prompt>$</prompt> <userinput>export M2_HOME=/usr/local/apache-maven/apache-maven-3.0.5
<prompt>$</prompt> export M2=$M2_HOME/bin
<prompt>$</prompt> export PATH=$M2:$PATH
<prompt>$</prompt> export MAVEN_OPTS='-Xms256m -XX:MaxPermSize=1024m -Xmx1024m'</userinput></screen>
</step>
<step>
<para>verify maven is setup with</para>
<screen><prompt>$</prompt> <userinput>mvn --install</userinput></screen>
</step>
</substeps>
</step>
<!-- the next five paragraphs were lifted from https://wiki.openstack.org/wiki/Documentation/HowTo#First-time_Contributors, we should figure out how to embed instead -->
<step>
<para>Create a Launchpad account: Visit
<link xlink:href="https://login.launchpad.net/+new_account">
https://login.launchpad.net/+new_account</link>After 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.)</para>
</step>
<step>
<para>Add at least one SSH key to your account profile. To
do this, follow the instructions
on <link xlink:href="https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair">
https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair"</link>.</para>
</step>
<step>
<para>Join The OpenStack Foundation: Visit
<link xlink:href="https://www.openstack.org/join">https://www.openstack.org/join</link>.
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.</para>
</step>
<step>
<para>the CLA: Every developer and contributor needs to
sign the Individual Contributor License agreement. Visit
<link xlink:href="https://review.openstack.org/">https://
review.openstack.org/</link> 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.</para>
</step>
<step>
<para>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:</para>
<screen><prompt>$</prompt><userinput>git config --global user.name "Firstname Lastname"
$ git config --global user.email "your_email@youremail.com" </userinput></screen>
</step>
<step>
<para>Install git-review. If pip is not already installed, use "<emphasis
role="bold">sudo easy_install pip</emphasis>" to install it on a Mac or
Ubuntu</para>
<screen><prompt>$</prompt><userinput>sudo pip install git-review</userinput></screen>
</step>
<step>
<para>Change to the directory</para>
<screen><prompt>$</prompt><userinput>cd /Users/yourusername/code</userinput></screen>
</step>
<step>
<para>Clone the openstack-manuals repository with</para><screen><prompt>$</prompt><userinput>git clone http://github.com/openstack/openstack-manuals.git</userinput></screen>
</step>
<step>
<para>Change directory to the pulled repository</para>
<screen><prompt>$</prompt><userinput>cd openstack-manuals</userinput></screen>
</step>
<step>
<para>Enter your Launchpad account information after testing
for ssh key setup with</para>
<screen><prompt>$</prompt><userinput>git review -s</userinput></screen>
</step>
</procedure>
</para>
<para>
<link xlink:href="https://blueprints.launchpad.net/openstack-manuals/+filebug" xlink:show="new">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.</link>
</para>
</section>
<section xml:id="fix-doc-bug">
<title>Fix a Documentation Bug</title>
<para>
<procedure>
<step>
<para>Note: For this example, we are going to assume bug
1188522 and change 33713</para>
</step>
<step>
<para>Bring up<link
xlink:href="https://bugs.launchpad.net/openstack-manuals"
>https://bugs.launchpad.net/openstack-manuals</link></para>
</step>
<step>
<para>Select a bug that is unassigned and that you can fix.
Syntax errors are the best ones to start off with.</para>
</step>
<step>
<para>Using oXygen, open the
/Users/&lt;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.</para>
</step>
<step>
<para>In the shell,</para>
<screen><prompt>$</prompt><userinput>cd /Users/&lt;username>/code/openstack-manuals/doc/admin-guide-cloud/</userinput></screen>
</step>
<step>
<para>Verify that you are on master with</para>
<screen><prompt>$</prompt><userinput>git checkout master</userinput></screen>
</step>
<step>
<para>Create your working branch off master with</para>
<screen><prompt>$</prompt><userinput>git checkout -b bug/1188522</userinput></screen>
</step>
<step>
<para>Verify that you have the branch open through
SourceTree</para>
</step>
<step>
<para>Correct the bug through oXygen. Toggle back and forth
through the different views at the bottom of the
editor.</para>
</step>
<step>
<para>Once the bug is fixed, verify that the documentation
can be built without errors by running</para>
<screen><prompt>$</prompt><userinput>mvn clean generate-sources</userinput></screen>
</step>
<step>
<para>Verify that the HTML page reflects your changes properly. You can open the file from the command line by using the "open" command</para>
<screen><prompt>$</prompt><userinput>open target/docbkx/webhelp/local/openstack-training/index.html</userinput></screen>
</step>
<step>
<para>Add the changes</para>
<screen><prompt>$</prompt><userinput>git add .</userinput></screen>
</step>
<step>
<para>Commit the changes</para>
<screen><prompt>$</prompt><userinput>git commit -a -m "Removed reference to volume scheduler in the computer scheduler
config and admin pages, bug 1188522"</userinput></screen>
</step>
<step>
<para>Submit the bug fix to Gerrit</para>
<screen><prompt>$</prompt><userinput>git review</userinput></screen>
</step>
<step>
<para>Track the Gerrit review process at<link
xlink:href="https://review.openstack.org/#/c/33713"
>https://review.openstack.org/#/c/33713</link>. Follow
and respond inline to the Code Review requests and
comments.</para>
</step>
<step>
<para>Your change will be tested, track the Jenkins testing
process at https://jenkins.openstack.org</para>
</step>
<step>
<para>If your change is rejected, complete the following steps:</para>
<substeps>
<step>
<para>Respond to the inline comments if any</para>
</step>
<step>
<para>Update the status to work in progress</para>
</step>
<step>
<para>Checkout the patch from the Gerrit change review</para>
<screen><prompt>$</prompt><userinput>git review -d 33713</userinput></screen>
</step>
<step>
<para>Follow the recommended tweaks to the files</para>
</step>
<step>
<para>Rerun</para>
<screen><prompt>$</prompt><userinput>mvn clean generate-sources</userinput></screen>
</step>
<step>
<para>add your additional changes to the change log</para>
<screen><prompt>$</prompt><userinput>git commit -a --amend</userinput></screen>
</step>
<step>
<para>Final commit</para>
<screen><prompt>$</prompt><userinput>git review</userinput></screen>
</step>
<step>
<para>Update the Jenkins status to change completed</para>
</step>
</substeps>
</step>
<step>
<para>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.</para>
</step>
</procedure>
</para>
<para>
<link xlink:href="https://blueprints.launchpad.net/openstack-manuals/+filebug" xlink:show="new">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.</link>
</para>
</section>
<section xml:id="submit-doc-bug">
<title>Submit a Documentation Bug Fix</title>
<para>
<procedure>
<step>
<para>Bring up<link
xlink:href="https://bugs.launchpad.net/openstack-manuals/+filebug"
>https://bugs.launchpad.net/openstack-manuals/+filebug</link></para>
</step>
<step>
<para>Give your bug a descriptive name</para>
</step>
<step>
<para>verify if asked that it is not a duplicate</para>
</step>
<step>
<para>Add some more detail into the description field</para>
</step>
<step>
<para>Once submitted, select the assigned to pane and select
assign to me</para>
</step>
<step>
<para>Follow the instructions for fixing a bug in the Fix a
Documentation Bug section.</para>
</step>
</procedure>
</para>
<para>
<link xlink:href="https://blueprints.launchpad.net/openstack-manuals/+filebug" xlink:show="new">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.</link>
</para>
</section>
<section xml:id="operator-create-branch">
<title>Create a Branch</title>
<para>
<note><para>This section is using the submission of this training material as the example</para></note>
<procedure>
<step>
<para>Create a bp/training-manuals
branch<programlisting>$ git checkout -b bp/training-manuals</programlisting></para>
</step>
<step>
<para>From the openstack-manuals repository, use the template <emphasis role="bold"
>user-story-includes-template.xml</emphasis> as the starting point for your user
story. <emphasis role="bold">bk001-ch003-associate-general.xml</emphasis> has at
least one other included user story that you can use for additional help.</para>
</step>
<step>
<para>Include the user story xml file into the <emphasis role="bold"
>bk001-ch003-associate-general.xml</emphasis> file. Follow the syntax of the
existing xi:include statements.</para>
</step>
<step>
<para>When your editing is completed. Double check Oxygen doesn't have any errors you
are not expecting.</para>
</step>
<step>
<para>Run maven locally to verify the build will run without errors
<programlisting>$ mvn clean generate-sources</programlisting></para>
</step>
<step>
<para>Add your changes into git<programlisting>$ git add .</programlisting></para>
</step>
<step>
<para>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.<programlisting>git commit -a
my very short summary
my more details go here. few sentences would be nice.
blueprint training-manuals</programlisting></para>
</step>
<step>
<para>Submit your patch for review<programlisting>$ git review</programlisting></para>
</step>
<step>
<para>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.</para>
</step>
<step>
<para>More details on branching can be found here under <link
xlink:href="https://wiki.openstack.org/wiki/Gerrit_Workflow">Gerrit
Workflow</link> and the <link xlink:href="http://git-scm.com/doc">Git
docs</link></para>
</step>
</procedure></para>
<para>
<link xlink:href="https://blueprints.launchpad.net/openstack-manuals/+filebug" xlink:show="new">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.</link>
</para>
</section>
<section xml:id="operator-add-training-content">
<title>Add Content to the Training Manuals</title>
<para>
<procedure>
<step><para><emphasis role="bold">Getting Accounts and Tools:</emphasis> 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 <link
xlink:href="http://docs.openstack.org/trunk/openstack-training/content/getting-tools-and-accounts.html"
>Getting Tools and Accounts</link> page.</para>
</step>
<step><para><emphasis role="bold">Pick a Card:</emphasis> Once you have your tools ready to go, you can
assign some work to yourself. Go to the <link
xlink:href="https://trello.com/board/openstack-training/51d6e5fee37248fd5b003de9"
>Training Trello/KanBan storyboard</link> 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.</para>
</step>
<step>
<para><emphasis role="bold">Create the Content:</emphasis> 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.</para>
</step>
<step>
<para>Open the file <emphasis role="bold">st-training-guides.xml</emphasis> with
your XML editor. All the content starts with the set file <emphasis
role="bold">st-training-guides.xml</emphasis>. The XML structure follows
the hierarchy Set -> Book -> Chapter -> Section. The <emphasis role="bold"
>st-training-guides.xml</emphasis> 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.</para>
</step>
<step>
<para>Create a branch using the card number as <emphasis role="bold"
>associate-card-XXX</emphasis> where XXX is the card number. Review
<link
xlink:href="http://docs.openstack.org/trunk/openstack-training/content/operator-create-branch.html"
>Creating a Branch</link> again for instructions on how to complete the
branch merge.</para>
</step>
<step>
<para>Copy the <emphasis role="bold">user-story-includes-template.xml
</emphasis>to <emphasis role="bold"
>associate-card-XXX.xml</emphasis>.</para>
</step>
<step>
<para>Open the <emphasis role="bold"
>bk001-ch003-asssociate-general.xml</emphasis> file and add <emphasis
role="bold">&lt;xi:include
href="associate-card-XXX.xml"></emphasis></para>
</step>
<step>
<para>Side by side, open<emphasis role="bold"> associate-card-XXX.xml</emphasis>
with your XML editor and open the <emphasis role="bold">ubuntu 12.04 install
guide</emphasis> with your HTML browser.</para>
</step>
<step>
<para>Find the HTML content to include. Find the XML file that matches the HTML.
Include the whole page using a simple href like <emphasis role="bold"
>&lt;xi:include href="associate-card-XXX.xml"></emphasis> or include a
section using xpath like <emphasis role="bold">&lt;xi:include
href="../basic-install/src/basic-install_controller-common.xml"
xpointer="xmlns(db=http://docbook.org/ns/docbook) xpath(//*[@xml:id =
'controller-os'])"></emphasis> . Review the <emphasis role="bold"
>user-story-includes-template.xml</emphasis> file for the whole
syntax.</para>
</step>
<step>
<para>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.</para>
</step>
<step>
<para>Verify the code is good by runnning mvn clean generate-sources and by
reviewing the local HTML in <link
xlink:href="target/docbkx/webhelp/local/training-guide/content/"
>file:///Users/(localUser)/code/openstack-manuals/doc/training-guide/target/docbkx/webhelp/local/training-guide/content/</link></para>
</step>
<step>
<para>Merge the branch</para>
</step>
<step>
<para>Move the card from Doing to Done</para>
</step>
</procedure>
</para>
<para>
<link xlink:href="https://blueprints.launchpad.net/openstack-manuals/+filebug" xlink:show="new">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.</link>
</para>
</section>
</section>
View Git Blame Copy Permalink