|
|
| (191 intermediate revisions by 30 users not shown) |
| Line 1: |
Line 1: |
| − | = How to edit OpenStack Documentation =
| + | Read the new content in the [http://docs.openstack.org/contributor-guide/index.html Documentation Contributor Guide]. |
| | + | {{OpenStack_Documentation_Navbar}} |
| | | | |
| − | == Introduction ==
| |
| − | In many cases, the easiest way to become a contributor to OpenStack is to participate in the documentation efforts. It requires no coding, just a willingness to read and understand the systems that you’re writing about. Because the documentation is treated like code, however, by participating in the documentation you will be learning the mechanics necessary to make contributions to OpenStack itself.
| |
| | | | |
| − | This document explains the tools and processes you will need to participate in OpenStack documentation, either as a writer, a reviewer, or simply a contributor who helps to organize the work that needs to be done. It discusses the following topics:
| + | ---- |
| − | | + | [[Category:Documentation]] |
| − | * Tools and content overview: This section gives you a basic overview of the existing documentation, and tooling. Use this section to find documentation on a particular subject.
| |
| − | * How to edit documentation: This section explains the action process involved in editing the document. Use this section to understand how to get set up to make changes, and how to go ahead and make and commit those changes.
| |
| − | * Policies and conventions: In order to keep all of the different pieces of documentation consistent, OpenStack documentation must follow certain conventions. Use this section to understand the various policies and conventions governing changes you might make.
| |
| − | * Working with bugs and reviewing patches: Like OpenStack code, documentation is tracked using blueprints and bug reports, and changes must be reviewed before they are merged. Use this section to understand how to report, triage, and review patches for bugs.
| |
| − | * Other Documentation resources: Use this section to find more information on the various and sundry other topics that come up in documentation, such as autodoc or translations.
| |
| − | | |
| − | == Tools and Content Overview ==
| |
| − | The tool used for the documentation depends on the audience for the docs.
| |
| − | | |
| − | We use DocBook to create OpenStack's web documentation for deployers, admins, and CLI and API users. We use [http://docutils.sourceforge.net/docs/user/rst/quickref.html ReStructured Text] (RST) files stored in source code for developer docs.
| |
| − | | |
| − | To work on the RST source files, find the /doc/source/ directory in a given OpenStack project to work on the source .rst files. These are built to http://docs.openstack.org/developer/<project>, for example, http://docs.openstack.org/developer/nova.
| |
| − | | |
| − | To work on the DocBook source files for admin guides, a working project exists in Github in the http://github.com/openstack/openstack-manuals project since DocBook documentation encompasses all OpenStack projects.
| |
| − | | |
| − | To work on the DocBook and WADL source files for http://api.openstack.org, look for the openstack/api-site project on Github and use the same [[GerritWorkflow]].
| |
| − | | |
| − | All API spec documentation that builds to http://docs.openstack.org/api is housed in image-api, identity-api, compute-api, netconn-api, and object-api repositories. Changes to these are approved by the core development team because they are specifications.
| |
| − | | |
| − | The DocBook builds are listed in the [[Documentation/Builds]] page, showing what source files are built from.
| |
| − | | |
| − | Here's a walk through of the contribution process showing how to pick up a doc bug and submit a patch for it.
| |
| − | | |
| − | {{#ev:youtube|rXzbNTqfJPU}}
| |
| − | | |
| − | === Audiences and Targets ===
| |
| − | OpenStack is broken up into several projects. Currently, the primary projects are:
| |
| − | | |
| − | * Compute (nova)
| |
| − | * Identity (keystone)
| |
| − | * Image (glance)
| |
| − | * Network (neutron)
| |
| − | * Block storage (cinder)
| |
| − | * Object storage (swift)
| |
| − | | |
| − | These projects have two basic audiences: developers and sysadmins (think operations or dev-ops). The RST-based documentation, because it automatically generates doc from docstrings in the code, is much more for a developer audience.
| |
| − | | |
| − | There are two types of developers that the developer documentation serves: Python developers who want to work on OpenStack code, and web developers who work with the OpenStack API.
| |
| − | | |
| − | === What Docs Go Where? ===
| |
| − | | |
| − | {| border="1" cellpadding="2" cellspacing="0"
| |
| − | |<tablebgcolor="#cccccc" >|wiki
| |
| − | | RST
| |
| − | |-
| |
| − | | Use for project docs, blueprint specs.
| |
| − | | Use for Python developer documentation and quick starts.
| |
| − | |-
| |
| − | | The audience is any project team member of OpenStack.
| |
| − | | The audience is Python developers who want to work on the project.
| |
| − | |-
| |
| − | | Output is per-page at wiki.openstack.org
| |
| − | | Output goes to docs.openstack.org/developer/nova.
| |
| − | |}
| |
| − | | |
| − | ==== wiki.openstack.org (wikitext or RST) ====
| |
| − | | |
| − | The OpenStack wiki contains project docs, specs for blueprints, and meeting information and minutes. If there's a page you want to keep an eye on (like Nova installations for example), add it to your Notifications list (under User > Settings > Notifications in the wiki).
| |
| − | | |
| − | ==== docs.openstack.org/developer/<projectname> (RST) ====
| |
| − | | |
| − | The RST pages stored with the project code should be written with a developer audience in mind, although many times you'll find there is overlap in what an admin needs to know and what a developer needs to know. High priorities for those sites are wider coverage of doc strings, API doc, i18N methodology, and architecture concepts that'll help developers.
| |
| − | | |
| − | ==== docs.openstack.org (DocBook 5) ====
| |
| − | | |
| − | As mentioned above, the source for this site is housed in Github in the http://github.com/openstack/openstack-manuals project, the Launchpad page for this project is https://launchpad.net/openstack-manuals. You can either build the output locally if you want, or just submit changes to the source XML through merge proposals. The OpenStack Jenkins build server builds the doc and copies the output to docs.openstack.org/trunk automatically thanks to the pom.xml files included in the source files.
| |
| − | | |
| − | * doc/$BOOK contains the DocBook XML source files and images
| |
| − | | |
| − | When editing DocBook documentation, please adhere to the DocBook 5 syntax. If you've used DocBook version 4 or earlier before, and you're not familiar with the changes that DocBook saw in V5.0, the [http://docbook.org/docs/howto/ Transition Guide] is a helpful read.
| |
| − | | |
| − | ==== Maven Plugin ====
| |
| − | The Cloud Doc Tools Maven plugin provides a build tool that Jenkins can use to build PDF and HTML from DocBook and WADL source files. It's maintained at https://github.com/rackerlabs/clouddocs-maven-plugin and we track bugs against the output in the openstack-manuals launchpad project.
| |
| − | | |
| − | The release notes are available on Github.
| |
| − | | |
| − | == How to edit OpenStack documentation ==
| |
| − | Actually editing OpenStack documentation is really a pretty straightforward process, once you get the hang of it. In general, it goes like this:
| |
| − | | |
| − | # Configure your computer to talk to all of the systems involved.
| |
| − | # Download the code from the appropriate repository.
| |
| − | # Make your changes.
| |
| − | # Commit changes to the repository.
| |
| − | # Changes are reviewed and merged.
| |
| − | | |
| − | This diagram shows the basic setup workflow:
| |
| − | | |
| − | [[File:WorflowDiagram.png|600px|frameless|Workflow Diagram]]
| |
| − | | |
| − | === Setup for First-time Contributors ===
| |
| − | First, thanks for contributing to docs! Secondly, you're just like a developer. In order to get started you need to follow the same steps followed by any other OpenStack developer:
| |
| − | | |
| − | # '''Create a Launchpad account''' and
| |
| − | # '''Join the OpenStack Foundation'''. Then you can
| |
| − | # '''Sign the Contributor License Agreement:''' All these steps are fully documented on the [[CLA]] page on this wiki.
| |
| − | # '''Setup git review''' and get familiar with the [[GerritWorkflow]]
| |
| − | | |
| − | Once you're done withe these preliminary steps you can proceed to
| |
| − | | |
| − | 6. Clone the openstack-manuals repository with:
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | git clone http://github.com/openstack/openstack-manuals.git
| |
| − | cd openstack-manuals
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | 7. Enter your Launchpad account information after testing for ssh key setup with git review -s.
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | git review -s
| |
| − | </nowiki></pre>
| |
| − | | |
| − | '''Note''': If you see any "Permission denied" errors at this step, go to [http://review.openstack.org review.openstack.org], log in, and check through all the items in your Settings link to ensure that everything matches. You may need to enter your SSH key in the Gerrit site (review.openstack.org).
| |
| − | | |
| − | '''Note''': If you get the error "We don't know where your gerrit is.", you will need to add a new git remote. The url should be in the error message. Copy that and create the new remote with this command:
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | git remote add gerrit ssh://<username>@review.openstack.org:29418/openstack/openstack-manuals.git
| |
| − | </nowiki></pre>
| |
| − | | |
| − | 8. Now you can work on the openstack-manuals locally and submit patches. Refer to the [[GerritWorkflow]] steps to contribute your changes.
| |
| − | | |
| − | That should get you started contributing to docs just like code. Read more for the details of what types of documentation go where.
| |
| − | | |
| − | === Downloading the documentation ===
| |
| − | | |
| − | The [https://github.com/rackerlabs/clouddocs-maven-plugin Clouddocs Maven Plugin] and a pom.xml configuration file in combination enable the builds to docs.openstack.org and api.openstack.org.
| |
| − | | |
| − | Here are the quick steps for getting started on the openstack-manuals project once you have acquired the source files:
| |
| − | | |
| − | 1. First install the Apache Maven project, and Git
| |
| − | | |
| − | The installation command will vary depending on your operating system.
| |
| − | | |
| − | On Mac OS X, with Macports:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | sudo port install maven3
| |
| − | #Install Git by referring to: https://help.github.com/articles/set-up-git#platform-mac
| |
| − | </nowiki></pre>
| |
| − | | |
| − | On Mac OS X, with Homebrew:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | brew install maven
| |
| − | #Install Git by referring to: https://help.github.com/articles/set-up-git#platform-mac
| |
| − | </nowiki></pre>
| |
| − | | |
| − | on Ubuntu:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | sudo apt-get install maven git
| |
| − | </nowiki></pre>
| |
| − | | |
| − | on Fedora:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | sudo yum install maven git
| |
| − | </nowiki></pre>
| |
| − | | |
| − | 2. Get a copy of the docs source files.
| |
| − | | |
| − | <pre><nowiki>
| |
| − | git clone https://github.com/openstack/openstack-manuals.git
| |
| − | </nowiki></pre>
| |
| − | | |
| − | The different manuals are in subdirectories of the
| |
| − | openstack-manuals/doc directory.
| |
| − | | |
| − | For example, the root directory of the OpenStack Virtual Image Guide
| |
| − | is openstack-manuals/doc/image-guide.
| |
| − | | |
| − | === Editor Options ===
| |
| − | | |
| − | We encourage the use of Oxygen XML Author for editing XML - it offers consistency in white space which makes diffs in review.openstack.org easier. If you prefer a text-based editor but with validation, you can use Emacs. 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
| |
| − | | |
| − | ==== Oxygen XML Acknowledgment ====
| |
| − | Thanks to the generosity of Oxygen in supporting open source projects, you can edit DocBook XML within the Oxygen Author or Editor by downloading a copy of the software from http://www.oxygenxml.com/. Send an email to anne at openstack dot org to request the license extension beyond the 30-day trial. As we have 10 floating licenses, you're encouraged to procure it through other channels if you work for a member OpenStack company.
| |
| − | | |
| − | ==== Oxygen and the Rackbook Framework ====
| |
| − | Thanks to Rackspace maintaining Oxygen tools that make authoring DocBook and WADL, we can offer a Rackbook framework. You can run directly from http://docs.rackspace.com/oxygen/. You will need to add a valid Oxygen license to use the application.
| |
| − | | |
| − | Alternatively, download the [http://feline.thingbag.net/oxygen-frameworks.zip oxygen-frameworks.zip] file. Next, download the following file to your system:
| |
| − | [http://wiki.openstack.org/Documentation/HowTo?action=AttachFile&do=get&target=defaults.xpr defaults.xpr]. Extract the oxygen-frameworks.zip file to ~/Library/Preferences (i.e. so you end up with /Users/your.username/Library/Preferences/com.oxygenxml.author). In Oxygen, go to Options->Import Global Options. Navigate to the downloaded defaults.xpr file and click Open.You should see a new bar of buttons and a Rackbook menu item. | |
| − | | |
| − | === Building Output Locally ===
| |
| − | | |
| − | 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. For example::
| |
| − | | |
| − | <pre><nowiki>
| |
| − | cd openstack-manuals/doc/image-guide
| |
| − | mvn clean generate-sources
| |
| − | </nowiki></pre>
| |
| − | | |
| − | The generated PDF documentation file is::
| |
| − | | |
| − | <pre><nowiki>
| |
| − | openstack-manuals/doc/image-guide/target/docbkx/webhelp/webhelp/local/image-guide/bk-imageguide-local.pdf
| |
| − | </nowiki></pre>
| |
| − | | |
| − | The root of the generated HTML documentation is:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | openstack-manuals/doc/image-guide/target/docbkx/webhelp/local/image-guide/content/index.html
| |
| − | </nowiki></pre>
| |
| − | | |
| − | For the install guides, there's a section in the pom.xml that tells the build whether to create the Ubuntu version of the guide, the RHEL/CentOS/Fedora version or the openSUSE version of the guide. Right now, the master branch pom.xml file defaults to Ubuntu with this section:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | <!-- This is set by Jenkins according to the branch. -->
| |
| − | <release.path.name>local</release.path.name>
| |
| − | <comments.enabled>1</comments.enabled>
| |
| − | <operating.system>apt</operating.system>
| |
| − | <!-- This is set by Jenkins to run twice for each similar operating system group -->
| |
| − | <profile.os>ubuntu</profile.os>
| |
| − | </nowiki></pre>
| |
| − | | |
| − | If you want to build the RHEL/CentOS/Fedora version of the install guide, change that section to this instead:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | <!-- This is set by Jenkins according to the branch. -->
| |
| − | <release.path.name>local</release.path.name>
| |
| − | <comments.enabled>1</comments.enabled>
| |
| − | <operating.system>yum</operating.system>
| |
| − | <!-- This is set by Jenkins to run twice for each similar operating system group -->
| |
| − | <profile.os>rhel;centos;fedora</profile.os>
| |
| − | </nowiki></pre>
| |
| − | | |
| − | And then re-run the '''mvn clean generate-sources''' command to get the RHEL output. You can also give these parameters as command to mvn like '''mvn clean generate-sources -Doperating.system=yum -Dprofile.os="rhel;centos;fedora"'''
| |
| − | | |
| − | If you want to build the openSUSE version of the install guide, change that section to this instead:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | <!-- This is set by Jenkins according to the branch. -->
| |
| − | <release.path.name>local</release.path.name>
| |
| − | <comments.enabled>1</comments.enabled>
| |
| − | <operating.system>zypper</operating.system>
| |
| − | <!-- This is set by Jenkins to run twice for each similar operating system group -->
| |
| − | <profile.os>opensuse</profile.os>
| |
| − | </nowiki></pre>
| |
| − | And then re-run the '''mvn clean generate-sources''' command to get the RHEL output. You can also give these parameters as command to mvn, like so:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | mvn clean generate-sources -Doperating.system=zypper -Dprofile.os=opensuse
| |
| − | </nowiki></pre>
| |
| − | | |
| − | The RST source is built into html using Sphinx so that it gets displayed on [http://docs.openstack.org/developer/nova Nova developer site], [http://docs.openstack.org/developer/swift/ Swift developer site], [http://docs.openstack.org/developer/glance/ Glance developer site], and [http://docs.openstack.org/developer/keystone/ Keystone developer site].
| |
| − | | |
| − | The DocBook source is built into html (webhelp) and PDF using XSLT transforms included with the DocBook project.
| |
| − | | |
| − | You can find tips for troubleshooting the build at: [[Documentation/Troubleshooting]]
| |
| − | | |
| − | === Workflow ===
| |
| − | The workflow for documentation matches the workflow for code - you download a branch, work on it locally, then commit the changes and propose a merge. Members of the openstack-doc-core team and others review your changes and after receiving enough +1 votes, an openstack-doc-core member can push +1 Approved. Once approved, your changes are merged into the main, published doc base, and the doc is built to its varying outputs with the Jenkins server.
| |
| − | | |
| − | ==== Detailed Workflow with Github and Gerrit ====
| |
| − | The page I always refer to for using Git and Gerrit for daily tasks is http://wiki.openstack.org/GerritWorkflow.
| |
| − | | |
| − | The workflow takes some startup work to get the accounts you need. First, you make a Launchpad account, and upload a public key. Then, you identify your Launchpad account to the git command line and away you go. You also need a Github account. The Launchpad account contains the signon and permissions information for the Gerrit workflow that we use for reviews.
| |
| − | | |
| − | Here's a sample for the documentation project specifically, once you get your Launchpad and Github accounts set up.
| |
| − | | |
| − | Create the directory where you want to store the doc source files, then switch to it.
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | mkdir ~/src/docs
| |
| − | | |
| − | cd ~/src/docs
| |
| − | </nowiki></pre>
| |
| − | | |
| − | Follow the steps in [[GerritWorkflow]], using a doc repo to get the source:
| |
| − | | |
| − | openstack-manuals
| |
| − | api-site
| |
| − | compute-api
| |
| − | identity-api
| |
| − | image-api
| |
| − | object-api
| |
| − | netconn-api
| |
| − | volume-api
| |
| − | | |
| − | As an example, here's how you check out all the files for the admin docs in openstack-manuals:
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | git clone git://github.com/openstack/openstack-manuals.git
| |
| − | </nowiki></pre>
| |
| − | | |
| − | Set up the Gerrit Change-Id hook, which is used for reviews, and run git review to run a script in the /tools directory which sets up the remote repository correctly:
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | cd $PROJECT
| |
| − | git review
| |
| − | </nowiki></pre>
| |
| − | | |
| − | Now make sure you have the latest from Github (docs move more slowly than code, but this is a good practice).
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | git checkout master
| |
| − | git pull origin master
| |
| − | </nowiki></pre>
| |
| − | | |
| − | Lastly, create a branch to do your work in that you'll do commits from:
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | git checkout -b TOPIC-BRANCH
| |
| − | </nowiki></pre>
| |
| − | | |
| − | Edit happily! You can use [http://www.oxygenxml.com/ Oxygen] since you're working on an open source project and we acknowledge their support.
| |
| − | | |
| − | When you're done with edits, if you've added any files do this in the working directory:
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | git add .
| |
| − | </nowiki></pre>
| |
| − | | |
| − | Next, you commit your changes with a message that'll be displayed in review.openstack.org, creating a change set:
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | git commit -a -m 'bug xxxxxxx Here's what I did in this set of changes'
| |
| − | </nowiki></pre>
| |
| − | | |
| − | Next, push your changes for review with:
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | git review
| |
| − | </nowiki></pre>
| |
| − | | |
| − | Go to the review site itself to see the review votes for the openstack-manuals project, at review.openstack.org. One of the core doc team members will review your edits and let you know if any changes are needed prior to merging them in.
| |
| − | | |
| − | ==== How to amend a review-in-progress ====
| |
| − | Within the repository for which you have a patch, make sure you don't have any work-in-progress changes that you have not committed yet. If needed, commit those changes and then restart your work by working in another branch as shown below.
| |
| − | | |
| − | Then do these steps:
| |
| − | | |
| − | :git checkout master
| |
| − | :
| |
| − | :git remote update
| |
| − | :
| |
| − | :git pull origin master
| |
| − | :
| |
| − | :git review -d 38710
| |
| − | | |
| − | where 38710 is the identifier found in the review.openstack.org URL for the patch set, such as https://review.openstack.org/#/c/38710/.
| |
| − | | |
| − | A new branch is created and checked out that you'll work within.
| |
| − | | |
| − | Then make your edits in the new branch that is created. Once edits are complete, do:
| |
| − | | |
| − | :git commit -a --amend
| |
| − | | |
| − | and in the vi editor, add more lines to your commit message to explain the reasons for the patch set.
| |
| − | | |
| − | Press Esc :wq to save the message and quit the VI editor.
| |
| − | | |
| − | Then do:
| |
| − | | |
| − | :git review -v
| |
| − | | |
| − | ==== How to a make changes to a stable branch ====
| |
| − | Let's say you have a docfix specific to the Grizzly documentation, which is closed. You can check out the stable/grizzly branch and make changes.
| |
| − | Be very considerate of what you are documenting specifically for the stable release and why. If it applies to the stable release and ongoing releases, you have to make your edits twice.
| |
| − | | |
| − | 1. Create a bug if one does not exist. Otherwise, note the bug number for your change.
| |
| − | | |
| − | 2. Make sure your repository is up to date:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | git fetch origin
| |
| − | </nowiki></pre>
| |
| − | | |
| − | 3. Create a topic branch by branching from grizzly, where 1234567 is the bug number:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | git checkout -b grizzly-bug/1234567 remotes/origin/stable/grizzly
| |
| − | </nowiki></pre>
| |
| − | | |
| − | 4. Make changes to your documents.
| |
| − | | |
| − | 5. Commit your changes:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | git add .
| |
| − | git commit -a
| |
| − | </nowiki></pre>
| |
| − | | |
| − | 5. In the commit message, add the bug #, like this:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | Updated xxx
| |
| − | | |
| − | bug: #1234567
| |
| − | | |
| − | author: diane fleming
| |
| − | </nowiki></pre>
| |
| − | | |
| − | 6. Submit your commit for review:
| |
| − | <pre><nowiki>
| |
| − | git review stable/grizzly
| |
| − | </nowiki></pre>
| |
| − | | |
| − | ==== How to a cherry-pick a change to a stable branch ====
| |
| − | Let's say a docfix was submitted to the master openstack-manuals branch, and you want this change to be reflected in the Grizzly documentation, which is closed. You can cherry pick the change and submit it.
| |
| − | | |
| − | Let's say we want to cherry-pick bug/948242 (review 7480) into grizzly.
| |
| − | | |
| − | 1. Make sure your repository is up to date:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | git fetch origin
| |
| − | </nowiki></pre>
| |
| − | | |
| − | 2. Create a topic branch by branching from grizzly:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | git checkout -b grizzly-bug/948242 remotes/origin/stable/grizzly
| |
| − | </nowiki></pre>
| |
| − | | |
| − | 3. On the Gerrit web page that contains the review you want to backport, click "cherry-pick" <br />
| |
| − | It's under Patch Set N, in the Download row. <br />
| |
| − | Copy the text, and then paste it into your terminal. <br />
| |
| − | For example, for review 7480, it looks like this:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | git fetch https://review.openstack.org/openstack/openstack-manuals refs/changes/80/7480/2 && git cherry-pick FETCH_HEAD
| |
| − | </nowiki></pre>
| |
| − | | |
| − | 4. Amend the commit log and submit for review. Add something like ''Cherry picked from http://review.openstack.org/7480'':
| |
| − | | |
| − | <pre><nowiki>
| |
| − | git commit --amend -m ''Cherry picked from http://review.openstack.org/7480''
| |
| − | git review stable/grizzly
| |
| − | </nowiki></pre>
| |
| − | | |
| − | == Policies and conventions ==
| |
| − | In order to ensure consistency across documents, the documentation team maintains a [[Documentation/Checklist]] you should check before committing your changes. This document explains the various files you will need. At a more granular level, you will also want to check out the [[Documentation/Conventions]] to make sure that you’re following all of the various markup conventions.
| |
| − | | |
| − | == Working with bugs and reviewing patches ==
| |
| − | All documentation work is tracked based on bugs. Some of these bugs are standing bugs, such as those for spelling errors or formatting, others are created automatically (via the DocImpact flag) and still others are created manually. Once the changes are made, they will need to be reviewed and approved, just like other OpenStack code.
| |
| − | | |
| − | === Understanding doc bugs ===
| |
| − | You can pick up a documentation bug or mark a bug as related to the documentation here, on the [https://bugs.launchpad.net/openstack/+bugs?field.tag=documentation aggregated list of documentation bugs from all OpenStack projects]. Let’s look at these bugs in a little more detail.
| |
| − | | |
| − | ==== DocImpact ====
| |
| − | When a developer adds code that affects the docs (for example, to add a new parameter), they add a DocImpact flag that automatically adds a bug to the system explaining what needs to be done. For more information, see [[Documentation/DocImpact]].
| |
| − | | |
| − | ==== Doc Bug Triaging Guidelines ====
| |
| − | Doc bugs are logged and triaged at http://bugs.launchpad.net/openstack-manuals. You can see how well we're doing with bugs [http://webnumbr.com/untouched-bugs-in-openstack-manuals- at this webnumbr]. Here are some definitions for Status and Importance so you can triage incoming doc bugs.
| |
| − | | |
| − | Status:
| |
| − | *New - Recently logged by a non-triaging person
| |
| − | *Incomplete - Needs additional information before it can be triaged
| |
| − | *Opinion - (not sure what to do with this one)
| |
| − | *Invalid - Not an issue for docs
| |
| − | *Won't Fix - Doc fixes won't fix the issue
| |
| − | *Confirmed - Acknowledged that it's a doc bug
| |
| − | *Triaged - Comments in the bug indicate its scope and amount of work to be done
| |
| − | *In Progress - Someone is working on it
| |
| − | *Fix Committed - A fix is in the repository; Gerrit sets this automatically
| |
| − | *Fix Released - A fix is published to the site; would like the CI team to set this automatically, bug filed [https://bugs.launchpad.net/openstack-ci/+bug/943413 bug 943413]
| |
| − | | |
| − | Importance:
| |
| − | *Critical - data will be lost if this bug stays in; or it's so bad that we're better off fixing it than dealing with all the incoming questions about it. Also items on the website itself that prevent access are Critical doc bugs.
| |
| − | *High - Definitely need docs about this or a fix to current docs; docs are incomplete without this. Work on these first if possible.
| |
| − | *Medium - Need docs about this within a six-month release timeframe.
| |
| − | *Low - Docs are fine without this but could be enhanced by fixing this bug.
| |
| − | *Wishlist - Would like this doc task done "some day" Would prefer to use this for "tasks" instead of "bugs" - mark a bug as low rather than putting it on the wishlist. When something is wrong with the doc, mark it as Low rather than Wishlist.
| |
| − | *Undecided - Recently logged by a non-triaging person or requires more research before deciding its importance.
| |
| − | | |
| − | The [[Documentation/DocComments|Documentation Comments]] should also be read for potential bug reports.
| |
| − | | |
| − | ==== Doc Bug Categories ====
| |
| − | | |
| − | If you want to help with bug fixing, here are some quick ways to select a certain subset of them
| |
| − | * [http://bugs.launchpad.net/openstack-manuals list of all documentation bugs]
| |
| − | * [https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=nova nova related documentation bugs]
| |
| − | * [https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=keystone keystone related documentation bugs]
| |
| − | * [https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=neutron neutron related documentation bugs]
| |
| − | * [https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=swift swift related documentation bugs]
| |
| − | * [https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=glance glance related documentation bugs]
| |
| − | * [https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=cinder cinder related documentation bugs]
| |
| − | * [https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=xen xen related documentation bugs]
| |
| − | * [https://bugs.launchpad.net/openstack-manuals/+bugs?field.tag=low-hanging-fruit low hanging fruit documentation bugs]
| |
| − |
| |
| − | === Reviewing Documentation ===
| |
| − | To see what documentation changes are ready for review, go to http://review.openstack.org and search for project:openstack/openstack-manuals. Or go to [https://review.openstack.org/#/q/status:open+project:openstack/openstack-manuals,n,z this page with the search already completed].
| |
| − | | |
| − | ==== Who can Review Documentation? ====
| |
| − | | |
| − | All community members can review doc patches and give them +1 or -1. Documentation Core members can give +2 or -2 votes and also click Approve so that the doc goes live, published to docs.openstack.org or api.openstack.org, based on the branch the patch is applied to. Docs core members should only click Approve if they've given a +2, otherwise the Jenkins build jobs are not triggered.
| |
| − | | |
| − | Because the Docs team is small, core members have the choice when reviewing and must use best judgement before publishing. Generally speaking, core members will wait for one other core member to +2 a doc patch. However if the change is small and the build works, a doc core member can +2 and Approve a change without waiting for another reviewer. This is a judgement call so docs core people should exercise caution when using this option.
| |
| − | | |
| − | There is a core training team being established, and they can +2 and Approve content in the openstack-manuals repo in the openstack-training folder only.
| |
| − | | |
| − | Once two community members approve a doc patch, a doc core member can also review it and push it through without waiting for a second core member.
| |
| − | | |
| − | ==== How to Review a Documentation Patch ====
| |
| − | | |
| − | Click a patch set.
| |
| − | | |
| − | Click a file that has changed to view the changes side by side.
| |
| − | | |
| − | Click the Review button and vote, then enter any comments about your review.
| |
| − | | |
| − | Usually small changes are easy to review online. For larger changes, you want to bring the changes locally to ensure they build correctly and to review the output as well as the source. Here's how:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | git review -d <nnnnn>
| |
| − | </nowiki></pre>
| |
| − | | |
| − | Where the value of nnnnn comes from the review.openstack.org URL, such as 11215 from the URL https://review.openstack.org/#/c/11215/.
| |
| − | | |
| − | The git review tool creates a new branch locally with the patch set. Change directories to the one containing the pom.xml for the deliverable you want to build and run:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | mvn clean generate-sources
| |
| − | </nowiki></pre>
| |
| − | | |
| − | Review the source and the output, and feel free to edit and patch it as well. When you're sure the build and output are good, run:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | git commit -a --amend
| |
| − | </nowiki></pre>
| |
| − | | |
| − | When the editor opens, write a new line telling the reason for the patch set.
| |
| − | | |
| − | Enter colon + w + q to save and exit the editor with the amended commit message. You can change the commit message to be more descriptive or to match the guidelines in [[GitCommitMessages]], but you do not need to add what your specific patchset changes. A reviewer can use the Gerrit interface to see the difference between patches.
| |
| − | | |
| − | Next, run:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | git review
| |
| − | </nowiki></pre>
| |
| − | | |
| − | To send your patch to patch the existing review.
| |
| − | | |
| − | == Translation ==
| |
| − | Translation efforts occur in the Transifex web site. Review the [[Documentation/Translation]] for all the technical details.
| |
