Contents
Note | |
---|---|
First create a GitHub account at github.com. |
Note | |
---|---|
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
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:
If you prefer vi, there are ways to make DocBook editing easier:
Install Maven
Create the
apache-maven
directory:# mkdir /usr/local/apache-maven
Copy the latest stable binary from http://maven.apache.org/download.cgi into
/usr/local/apache-maven
.Extract the distribution archive to the directory you wish to install Maven:
# cd /usr/local/apache-maven/ # tar -xvzf apache-maven-x.x.x-bin.tar.gz
The
apache-maven-
subdirectory is created from the archive file, wherex.x.x
x.x.x
is your Maven version.Add the M2_HOME environment variable:
$ export M2_HOME=/usr/local/apache-maven/apache-maven-x.x.x
Add the M2 environment variable:
$ export M2=$M2_HOME/bin
Optionally, add the MAVEN_OPTS environment variable to specify JVM properties. Use this environment variable to specify extra options to Maven:
$ export MAVEN_OPTS='-Xms256m -XX:MaxPermSize=1024m -Xmx1024m'
Add the M2 environment variable to your path:
$ export PATH=$M2:$PATH
Make sure that JAVA_HOME is set to the location of your JDK and that $JAVA_HOME/bin is in your PATH environment variable.
Run the mvn command to make sure that Maven is correctly installed:
$ mvn --version
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 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 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 .
The CLA: Every developer and contributor needs to sign the Individual Contributor License agreement. Visit https://review.openstack.org/ and click the 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 "[email protected]"
Install git-review. If pip is not already installed, run
easy_install pip
asroot
to install it on a Mac or Ubuntu.# pip install git-review
Change to the directory:
$ cd /Users/
username
/codeClone the openstack-manuals repository:
$ git clone http://github.com/openstack/openstack-manuals.git
Change directory to the pulled repository:
$ cd openstack-manuals
Test the ssh key setup:
$ git review -s
Then, enter your Launchpad account information.
Note For this example, we are going to assume bug 1188522 and change 33713
Select an unassigned bug that you want to fix. Start with something easy, like a syntax error.
Using oXygen, open the
/Users/
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.username
/code/openstack-manuals/doc/admin-guide-cloud/bk-admin-guide-cloud.xmlIn the shell,
$ cd /Users/
username
/code/openstack-manuals/doc/admin-guide-cloud/Verify that you are on master:
$ git checkout master
Create your working branch off master:
$ 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.
After you fix the bug, run maven to verify that the documentation builds successfully. To build a specific guide, look for a
pom.xml
file within a subdirectory, switch to that directory, then run the mvn command in that directory:$ 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"
Build committed changes locally by using tox. As part of the review process, Jenkins runs gating scripts to check that the patch is fine. Locally, you can use the tox tool to run the same checks and ensure that a patch works. Install the tox package and run it from the top level directory which has the
tox.ini
file.# pip install tox $ tox
Jenkins runs the following four checks. You can run them individually:
Niceness tests (for example, to see extra whitespaces). Verify that the niceness check succeeds.
$ tox -e checkniceness
Syntax checks. Verify that the syntax check succeeds.
$ tox -e checksyntax
Check that no deleted files are referenced. Verify that the check succeeds.
$ tox -e checkdeletions
Build the manuals. It also generates a directory
publish-docs/
that contains the built files for inspection. You can also usedoc/local-files.html
for looking at the manuals. Verify that the build succeeds.$ tox -e checkbuild
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.
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.
Note | |
---|---|
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. Filebk001-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 existingxi: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. Look for a
pom.xml
file within a subdirectory, switch to that directory, then run the mvn command in that directory:$ 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 more details go here. A few sentences would be nice. blueprint training-manuals
Build committed changes locally using tox. As part of the review process, Jenkins runs gating scripts to check that the patch is fine. Locally, you can use the tox tool to run the same checks and ensure that a patch works. Install the tox package and run it from the top level directory which has the
tox.ini
file.# pip install tox $ tox
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.
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 do not have a Trello account, no problem, just create one. Email [email protected] 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. Thest-training-guides.xml
file holds the set level. Notice the set file usesxi: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
whereXXX
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
toassociate-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 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-guides/target/docbkx/webhelp/training-guides/content/.Merge the branch.
Move the card from Doing to Done.