openstack-manuals/doc/training-guide/operator-editing-code.xml
Colin McNamara a87574826b fixed directory structure
Change-Id: I064924668d6ec4ad25b0d14fdcef14059cabf1e7
2013-09-10 11:33:35 -07:00

360 lines
20 KiB
XML

<?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><userinput>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'</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>
</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>
</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>
</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>
</section>
</section>