Jump to: navigation, search

Difference between revisions of "Documentation/HowTo"

(Building Output Locally: - Links to tox.ini in git.openstack.org)
(Oxygen and the Rackbook Framework)
Line 230: Line 230:
 
==== Oxygen XML Acknowledgment ====
 
==== 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/. We have been given 10 floating licenses, but they are all claimed. You're encouraged to procure it through other channels if you work for a member OpenStack company.
 
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/. We have been given 10 floating licenses, but they are all claimed. You're encouraged to procure it through other channels if you work for a member OpenStack company.
 
==== Oxygen and the Rackbook Framework ====
 
Due to Rackspace maintaining Oxygen tools that make authoring DocBook and WADL easier, 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 ===
 
=== Building Output Locally ===

Revision as of 21:01, 21 May 2015

OpenStack Documentation

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:

  • 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 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://developer.openstack.org, look for the http://github.com/openstack/api-site project on Github and use the same development workflow.

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.

For information about DocBook, see DocBook: The Definitive Guide.

Here's a video walk through of the contribution process showing submit a patch for a doc bug:

Contribute to OpenStack Documentation - a Walk Through

OpenStack Projects

The OpenStack Documentation program focuses on the documentation for the following primary projects:

  • Compute (nova)
  • Identity (keystone)
  • Image (glance)
  • Network (neutron)
  • Block storage (cinder)
  • Object storage (swift)


The Documentation program has cross-project liaisons (CPLs) who assist with subject matter questions, reviews, doc bug triaging, and patching docs. Refer to documentation cross-project liasons for a list, and if you are interested in becoming a CPL for docs, contact the Docs PTL.

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.

The developer documentation serves both Python developers who want to work on OpenStack code and web developers who work with the OpenStack API.

What Docs Go Where?

Refer to Documentation/ContentSpecs for a description of many documents. A long listing of which repos house which documents is at Documentation/Builds. Generally this table describes the patterns for what goes where.

Specialty teams meet weekly to work on specific documents. Here is a list of the contact person for each specialty team:

  • High Availability Guide: Matt Griffin
  • Install Guides: Karin Levenstein
  • Networking Guide: Nick Chase
  • Security Guide: Bryan Payne
  • User Guides: Lana Brindley (Loquacities)

Note: Some content is completely generated using openstack-doc-tools, such as the configuration option tables and the CLI reference information. You will see this warning in the source file: <!-- This file is automatically generated, do not edit --> When you see this, you can still update the file using the openstack-doc-tools tool kit.

wiki RST Docbook
Use for project docs, such as this HowTo page. Use for End User Guide which is migrating to RST, Python contributor developer documentation and quick starts. Use for more in-depth documentation that provides context and learning opportunities.
The audience is any project team member of OpenStack. The audience is Python developers who want to work on the project. For the migrating content, it's for both end users and admin users. The audience is typically users of OpenStack, but developers are a secondary audience.
Output is per-page at wiki.openstack.org Output goes to docs.openstack.org/developer/<projectname>. Output goes to docs.openstack.org

wiki.openstack.org (wikitext or RST)

The OpenStack wiki contains project docs, legacy specs for blueprints, and meeting information and minutes. If there's a page you want to keep an eye on, add it to your Watchlist (add via Page > Watch and see all entries suing under YourLogin > Watchlist in the wiki).

If you add documentation specific pages, mark them as Documentation related with adding [[Category:Documentation]] at the end of the page.

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.

RST stands for ReStructured Text, a simple markup syntax that can be built with Sphinx. Read more at http://sphinx-doc.org/rest.html.

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 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 Transition Guide is a helpful read.

Maven Plugin

The Cloud Doc Tools Maven plug-in 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/stackforge/clouddocs-maven-plugin. We track bugs against the output in the OpenStack Core Infrastructure launchpad project.

The release notes are available on Github.

For the openstack-manuals, a parent pom contains the clouddocs-mvn-plugin version. For information about parent pom files, see https://maven.apache.org/guides/introduction/introduction-to-the-pom.html.

Edit the OpenStack Wiki

Read the tips on how to use this wiki before you go on and edit the pages yourself.

Edit OpenStack RST and/or DocBook documentation

Editing OpenStack documentation is a straightforward process, once you get the hang of it. OpenStack uses the same process for code, infrastructure and documentation, just form (docbook, python) and tools differ.

In general, it goes like this:

  1. Configure your computer to talk to all of the systems involved.
  2. Download the code from the appropriate repository.
  3. Make your changes.
  4. Commit changes to the repository.
  5. Changes are reviewed and merged.

This diagram shows the basic set up workflow:

Workflow Diagram

Set up for first-time contributors

Thanks for contributing to docs!

To get started, you must complete the following steps just like any other OpenStack developer. The steps are detailed in the Getting Started section of the Infrastructure Manual and here is an overview:

  1. Create a Launchpad account (which will authenticate as UbuntuOne).
  2. Join the OpenStack Foundation. Then you can
  3. Sign the Contributor License Agreement:
  4. Setup git review and get familiar with the Development Workflow

For documentation specifically, we've got a First Timers Step-by-Step Tutorial page also.

Download the documentation

Use the Clouddocs Maven Plugin and a pom.xml configuration file in combination to build docs to docs.openstack.org and developer.openstack.org.

There is no need to install the plugin; it will be downloaded automatically when you run Maven to generate a book.

Follow these steps to get started:

1. Install the Apache Maven project, and Git

The installation command depends on your operating system.

On Mac OS X, with Macports:

sudo port install maven3

Install Git by referring to: https://help.github.com/articles/set-up-git#platform-mac

On Mac OS X, with Homebrew:

brew install maven

Install Git by referring to: https://help.github.com/articles/set-up-git#platform-mac

on Ubuntu:

sudo apt-get install maven git git-review

on Fedora:

sudo yum install maven git git-review

on Windows:

2. Get a copy of the docs source files:

git clone https://github.com/openstack/openstack-manuals.git

Each book has its own folder in the openstack-manuals/doc directory.

For example, the root directory of the OpenStack Virtual Image Guide is openstack-manuals/doc/image-guide.

cd to the openstack-manuals directory before continuing.

3. Enter your Launchpad account information after testing for ssh key set up with the following command:

git review -s

Note: If you see any "Permission denied" errors at this step, go to 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:

git remote add gerrit ssh://<username>@review.openstack.org:29418/openstack/openstack-manuals.git

Note: If you see "git: 'review' is not a git command. See 'git --help'" at this step and you're on a Mac, run:

sudo pip install git-review

For more information, go to http://blog.invisible.ch/2013/05/06/7-getting-git-review-to-work/

4. Work on the openstack-manuals locally and submit patches. See the development workflow 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.

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:

If you prefer vi, there are ways to make DocBook editing easier:

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/. We have been given 10 floating licenses, but they are all claimed. You're encouraged to procure it through other channels if you work for a member OpenStack company.

Building Output Locally

The project uses a tox.ini file with specific sections that run jobs.

Basically, you run tox -e <jobname> to run that job name.

To build RST docs:

tox -e docs

To build all docs (DocBook and RST):

tox -e checkbuild

Note: If you don't want to use tox, install these prereqs locally: pip install sphinx; pip install openstackdocstheme and then switch to the directory containing a conf.py and run sphinx-build /path/to/source/ path/to/build/ to get html output by default.

Because Sphinx builds have dependent requirements it is best to work with in a virtual environment. Fortunately the openstack-manuals project already has tox set up so that you can create a virtualenv that contains the required dependencies. To use it, do this on a Mac or Ubuntu machine with Python and pip already installed:

Clone the openstack-manuals repo.

Change directories into openstack-manuals.

Run this:

tox -e py27

When you get a congratulations message, run this:

Mac/Ubuntu:

source .tox/py27/bin/activate

Windows:

source .tox/py27/Scripts/activate

Your prompt should now have (py27) as a preface.

Now you have all the pre-requisites installed and can run additional tox commands. To see the list of commands, view or edit tox.ini in the openstack-manuals directory. To build the RST docs, run:

tox -e docs

This will run sphinx-build doc/playground-user-guide/source/ doc/playground-user-guide/build/html.

When the build is finished, you can open doc/playground-user-guide/build/html/index.html to view the resulting output.

To build DocBook Locally without a Python environment

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:

cd openstack-manuals/doc/image-guide
mvn clean generate-sources

The generated PDF documentation file is:

openstack-manuals/doc/image-guide/target/docbkx/webhelp/image-guide/image-guide.pdf

The root of the generated HTML documentation is:

openstack-manuals/doc/image-guide/target/docbkx/webhelp/image-guide/content/index.html

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/SLES version of the guide. Right now, the master branch pom.xml file defaults to Ubuntu with this section:

<!-- 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>

If you want to build the RHEL/CentOS/Fedora version of the install guide, change that section to this instead:

<!-- 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>

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/SLES version of the install guide, change that section to this instead:

<!-- 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;sles</profile.os>

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:

mvn clean generate-sources -Doperating.system=zypper -Dprofile.os='opensuse;sles'

The RST source is built into html using Sphinx so that it gets displayed on Nova developer site, Swift developer site, Glance developer site, and 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

Using Tox to check builds

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ː

  1. Install python-tox (http://testrun.org/tox/latest/):
    • # easy_install tox
  2. From the repository base directory, check all booksː
    • $ tox

You can also set up your own Python 2.7 environment for running these individually in a virtualenv.

Run this:

tox -e py27

When you get a congratulations message, run this:

Mac/Ubuntu:

source .tox/py27/bin/activate

Windows:

source .tox/py27/Scripts/activate

Your prompt should now have (py27) as a preface. The following individual checks are also availableː

  • 'tox -e checkniceness' - to run the niceness tests (for example, to see extra whitespaces)
  • 'tox -e checksyntax' - to run syntax checks
  • 'tox -e checkdeletions' - to check that no deleted files are referenced
  • 'tox -e checkbuild' - to actually build the manual(s). This will also generate a directory publish-docs that contains the built files for inspection. You can also use doc/local-files.html for looking at the manuals.
  • 'tox -e checklang' - to check all translated manuals

Notesː

  • The above checks only test the files of the most recent commit, so first 'git commit' everything, then run 'tox'.
  • To check all files, pass '--force' as parameter to the tox command, for example 'tox -e checkniceness -- --force'. The '--' is important, it passes the option down to the validation tool.
  • Ubuntu and Debian require the following additional dependencies: gcc, gettext, python-dev, libxml2-dev, libxslt1-dev, zlib1g-dev
  • RHEL and variants including Fedora, openSUSE and SUSE Linux Enterprise require the following additional dependencies: gcc, python-devel, libxml2-devel, libxslt-devel
  • If Tox stops working, try 'tox --recreate' to rebuild the environment.

Refː Ajaeger's Validating OpenStack API projects

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.

This is fully explained in the Infrastructure Manual.

Detailed Workflow with Github and Gerrit

The page I always refer to for using Git and Gerrit for daily tasks is development workflow.

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.

mkdir ~/src/docs

cd ~/src/docs

Follow the steps in Development Workflow, 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:

git clone  git://git.openstack.org/openstack/openstack-manuals.git

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:

cd openstack-manuals
git review

Now make sure you have the latest from Github (docs move more slowly than code, but this is a good practice).

git checkout master
git pull origin master

Lastly, create a branch to do your work in that you'll do commits from:

git checkout -b TOPIC-BRANCH

Edit happily! You can use 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:

git add .

Next, you commit your changes with a detailed message that'll be displayed in review.openstack.org, creating a change set,

git commit -a

A VI editor will open were you now can add the reasons for your change and mention any closed bugs. Follow the conventions about git commit messages giving a good patch description, adding a summary line as first line, followed by an empty line, descriptive text, backport lines and bug information:

Nice title

Enhance foo to do bar.

backport: havana
Closes-Bug: #123456

Press Esc :wq to save the message and quit the VI editor.

Next, push your changes for review with:

git review

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/.

You may also find that someone else has patched your patch, so you would also have to do these steps to get a local copy of the changes.

When you do the git review -d nnnnnn command, 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 update the commit message as needed. Note that comments about the revisions (what has changed in a new change) belong into the gerrit comments and not in the git commit message. So, if you want to say "Fixed all review comments", please do this in review.openstack.org as review comment. If on the other hand, your new revision does not match the commit message any more, update it so that a first time reviewer of the change will understand the new change.

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:

git fetch origin

3. Create a topic branch by branching from icehouse, where 1234567 is the bug number:

git checkout -b icehouse-bug/1234567 remotes/origin/stable/icehouse

4. Make changes to your documents.

5. Commit your changes:

git add .
git commit -a 

In the commit message, add the bug #, like this:

Updated xxx

Closes-Bug: #1234567

6. Submit your commit for review:

git review

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 Icehouse documentation, which is closed. You can cherry pick the change and submit it.

Scenario: Let's say we want to cherry-pick bug/ficeth0 (review 52526) into icehouse.

1. Wait for the change to be merged into the master branch.

2. Make sure your repository is up to date:

git fetch origin

3. Create a topic branch by branching from icehouse:

git checkout -b icehouse-bug/ficeth0 remotes/origin/stable/icehouse

4. On the Gerrit web page that contains the review you want to backport, click "cherry-pick"
It's under Patch Set N, in the Download row.
Copy the text, and then paste it into your terminal.
For example, for review 52526, it looks like this:

  • Note: use the -x option with the cherry-pick command to preserve git history metadata in the cherry pick commit message.
git fetch https://review.openstack.org/openstack/openstack-manuals refs/changes/26/52526/1 && git cherry-pick -x FETCH_HEAD

5. Resolve any conflicts, run unit tests and then submit for review:

git commit --amend

6. Make sure you retain original Change-Id from the previous commit message; this will facilitate tracking of backports into all affected branches.

You may add "Cherry-pick from review.openstack.org/URL" to the commit message to make it easier for reviewers.

git review

NOTE: if cherry-pick is clean and does not require resolving conflicts, you may use 'Cherry Pick to' button in Gerrit WebUI from the original master review page.

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.

When to write a blueprint description in docs-specs

A write-up in docs-specs can be used for:

  • adding a large portion to an existing deliverable to ensure buy-in from the core doc team
  • adding an entirely new deliverable to the docs project
  • any work that requires both content and tooling changes, such as the addition of the API reference site, for sure that work needed a blueprint
  • any large reorganization of a deliverable or set of deliverables
  • automation work that will need to be designed prior to proposing a patch
  • work that should definitely be discussed at a summit

Use bugs against openstack-manuals or openstack-api-site for:

  • known content issues, even if you have to do multiple patches in order to close the bug
  • additions of content that is just plain missing
  • known errors in the document

We want to balance the need for up-front approval with "just write it already" -- it's a balancing act and we lean towards "just write" in general.

A spec needs two +2 votes from the docs-specs-core team, consisting of:

  • Anne Gentle
  • Andreas Jaeger
  • Bryan Payne (for security-docs blueprint specifications)
  • Sean Roberts (for training-guides blueprint specifications)


Git commit messages and backports

Besides the information about GitCommitMessages, patches touching files that might get backported (Install Guides, Configuration Reference and common directory) get annotated with information about backports:

Any patch to the master branch must specify in the commit message whether the patch should be backported. For example:

backport: icehouse

to backport to a single branch or for backporting to multiple branches:

backport: icehouse havana

or if no backporting is needed:

backport: none

Always add the backport line for potential backport patches.

Note: There's a blueprint to automate backporting based on this information. For full details see the Commit log annotation-driven auto-backports blueprint.


Shared account information for doc or search management

There are some areas where only trusted infrastructure or doc team members have access to configure or manage part of the documentation site. Examples include:

  • FTP credentials to the Cloud Sites that houses the files for docs.openstack.org and developer.openstack.org.
  • Google Custom Search Engine (CSE) configuration.
  • Google Analytics account information and configuration.

For these shared identities, we use this process to ensure limited access to the information that grants access.

  • At the Summit or another in-person meeting, ensure we verify identities with IDs similar to a GPG party.
  • With those identities and shared trust in place, create a server with a place to store the account information.
  • Enable access to the shared account info by granting access to the server.

Currently the infrastructure core team and Docs PTL has access to the FTP credentials. The Docs PTL has access to the Google CSE information and the Google Analytics account information. The Docs PTL can grant access to the shared Google information. The infrastructure core team can grant access to the FTP credentials.

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.

Anyone can join the openstack-doc-bugs team by getting a Launchpad account and going to https://launchpad.net/~openstack-doc-bugs and joining the team, no need for approvals.

Please go through the triaging process and look for possible duplicate bugs before working on a bug. Do not work on a doc bug until it is set to Confirmed. Ideally you'll get another person to confirm the bug for you. Once the changes are made in a patch, they are 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 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 in Launchpad. You can see how well we're doing with bugs for openstack-manuals or for openstack-api-site. 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. Don't set this manually.
  • Fix Released - A fix is published to the site.

Since we release all documentation directly on docs.openstack.org, "Fix Committed" is deprecated. Bugs should have the status "Fix Released". If patches contain the line "Closes-Bug: #12345" (see git commit messages for details), our CI infrastructure will set a bug automatically to "Fix Released" once a bug is merged.

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 Comments should also be read for potential bug reports.

Launchpad projects and repositories

The Documentation team uses two projects for tracking doc bugs across OpenStack:

  1. Launchpad bug area openstack-manuals is the default for doc bugs and should be used for docs sourced from these repositories:
    • clouddocs-maven-plugin
    • openstack-doc-tools
    • openstack-manuals,
    • operations-guide
    • security-doc
  2. Launchpad bug area openstack-api-site is used for all the API repositories:
    • api-site
    • compute-api
    • identity-api
    • image-api
    • netconn-api
    • object-api
    • volume-api

Doc Bug Categories

If you want to help with bug fixing, here are some quick ways to select a certain subset of them:

Reviewing Documentation

To see what documentation changes are ready for review, use the Documentation Program Dashboard, a custom URL rendered at http://is.gd/openstackdocsreview. This dashboard is organized in groupings based on the audience for the documentation.

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 developer.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 judgment 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.

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.

Repositories and core team

The OpenStack Docs team is core for api-site, openstack-manuals, operations-guide and openstack-doc-tools.

For the following repositories that are part of the Documentation program special rules apply:

  • training-guides: Has a separate core team.
  • security-doc: Has a separate core team consisting of docs team members and security team members. The rule here is that each patch needs an approval by a Docs core and a security team core.
  • api projects: Here both the OpenStack project core and the Docs core are cores, for example for image-api the keystone cores are cores as well.
  • docs-specs: Has a separate core team, see docs-specs section

How to Review a Documentation Patch

We have established some review guidelines for documentation to guide documentation reviewers.

  1. Click a patch set.
  2. Click a file that has changed to view the changes side by side.
  3. Click on the Jenkins gate that is called "checkbuild" (for the manuals it is "gate-openstack-manuals-tox-doc-publish-checkbuild") and review the built manuals to see how the change will look on the web page and as PDF.
  4. 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:

git review -d <nnnnn>

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:

mvn clean generate-sources

Alternatively, you can use tox to. build all the books which are affected by changes in the patch set. The program will output which books have been build since their content was changed.

tox -e check-build

To review the locally built documenation open the file doc/local-files.html in your browser and click on the guides you want to review or open the file publish-docs/index.html. See also using Tox to check builds.

Review the source and the output, and feel free to edit and patch it as well. Ensure that the patch adheres to the Documentation/Conventions for OpenStack documentation and uses standard English. When you're sure the build and output are good and have changed the patch, run:

git commit -a --amend

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 should not to add what your specific patchset changes. A reviewer can use the Gerrit interface to see the difference between patches.

Next, run:

git review

To send your patch to patch the existing review.

Set WorkInProgress (WIP) during review

The WIP tag tells anyone looking at a change that more updates are still needed. Both the change's owner and any core reviewer can set the WIP statusː

  • A change owner can set this tag on their own review to mark that additional changes are still being made, and to avoid unnecessary reviews while that happens.
  • A core reviewer can set the WIP tag to acknowledge that a contributor will definitely need to do more work on a change rather than merely expressing an opinion on its readiness. This can be a great convenience to fellow reviewers. It allows the core reviewer to politely send the message that the change needs additional work while simultaneously removing it from the list of ready changes until that happens.


To add the WIP tag:

  1. Click a patch set.
  2. Click the Review button.
  3. Choose the '-1 Work In Progress' from the Workflow options, enter comments (optional).
  4. Click Publish Comments.

This sets a -1 and informs everyone that the patch is WorkInProgress.

Translation

Translation efforts occur in the Transifex web site. Review the Documentation translation page for all the technical details.

Migration

We're migrating most existing documentation from DocBook to RST.