Jump to: navigation, search

Difference between revisions of "Documentation/Release"

(Documentation Release)
(Actions on Final Branch)
Line 26: Line 26:
 
# Check in this final branch for review.  
 
# Check in this final branch for review.  
 
# Notify the CI team of the branch that is ready for cutting as a release branch.
 
# Notify the CI team of the branch that is ready for cutting as a release branch.
# Ask the CI team to create tags for each documentation repository
+
# Ask the CI team to create tags for each documentation repository.
  
 
After the branch is created, do the following:
 
After the branch is created, do the following:
* Update the .gitreview file to add <code>defaultbranch=stable/icehouse</code> to indicate the branch each time when using git review.
+
* Update the .gitreview file to add <code>defaultbranch=stable/juno</code> to indicate the branch each time when using git review.
* Update doc-test.conf to include <code>release_path = icehouse</code> so that publishing is done to /icehouse instead of to /trunk.
+
* Update doc-test.conf to include <code>release_path = juno</code> so that publishing is done to /juno instead of to /trunk.
 
* Update tox.ini so that the <code>testenv:publishdocs</code> section only builds the install-guide and config-reference, and no publishing of www is done:
 
* Update tox.ini so that the <code>testenv:publishdocs</code> section only builds the install-guide and config-reference, and no publishing of www is done:
 
<pre>
 
<pre>

Revision as of 21:22, 14 October 2014

For DocBook documentation in openstack-manuals, we have different branches available for authoring - the StableBranch for prior releases and master or HEAD which corresponds to docs.openstack.org/trunk. The Continuous Integration work keeps docs building to docs.openstack.org/trunk and docs.openstack.org/{folsom|havana} based on the branch they are checked into.

At release time, have one doc contributor (or the doc lead) follows the instructions below to make a release branch.

Documentation Release

OpenStack continuously publishes docs from the master branch. It doesn't track with milestone releases, as there are not enough contributors to make that happen. When the number of doc bugs for a specific release seems tolerable (that is, publishing the "release" documents won't cause more questions than it answers), we follow these steps to create a stable branch that is published to a named release directory on the docs site, such as docs.openstack.org/icehouse. However, only certain documents are "released" such as the Installation Guides and the Configuration Reference.

Here are the checklist steps for creating a release of the Documentation from the http://github.com/openstack/openstack-manuals repository.

Pre-requisites

Create a local branch that will become the stable/releasename branch. Then, do all these things to it:

Actions on Final Branch

  1. Change all pom.xml files:
    • Update the <plugin><version> to the known version of the Cloud docs plugin that works with this book. For the Icehouse release, use 1.15.0. Avoid the use of SNAPSHOT in a release deliverable since it's a work-in progress untested build of the plugin.
    • Leave <release.path.name>unknown</release.path.name> or <release.path.name>local</release.path.name> alone, Jenkins fills that in. We could switch all of them to use <release.path.name>local</release.path.name> as it makes the most logical sense.
  2. Change all the book files:
    • Ensure the revision history table notes the final update.
    • Ensure the book file contains the date of final publish.
    • Ensure the book file contains the correct release name and not "trunk". Use "current" for continuously published books.
  3. Create a test build of each book and look at the PDF and HTML output, ensuring images are displaying properly and that the PDF and RSS links work.
  4. Change the index.html files in the /www folder to point to the release name version of each deliverable.
  5. Check in this final branch for review.
  6. Notify the CI team of the branch that is ready for cutting as a release branch.
  7. Ask the CI team to create tags for each documentation repository.

After the branch is created, do the following:

  • Update the .gitreview file to add defaultbranch=stable/juno to indicate the branch each time when using git review.
  • Update doc-test.conf to include release_path = juno so that publishing is done to /juno instead of to /trunk.
  • Update tox.ini so that the testenv:publishdocs section only builds the install-guide and config-reference, and no publishing of www is done:
commands = 
  # Commands for stable/icehouse only:
  openstack-doc-test --check-build --publish --only-book install-guide --only-book config-reference --verbose

Continuous Integration and Automation

  • Ensure any incubated project now builds to /trunk.

Update Google site map and Google Custom Search Engine

This step requires the use of a Google account that administers the paid Custom Search Engine. Currently Anne Gentle and Todd Morey have these credentials.

  • Ensure that the sitemap.xml stored on the web server contains links to the latest release. Using http://www.freesitemapgenerator.com, it's an online generator tool with a 5,000 page limit.
  • Ensure that the past release site is removed from the Google Custom Search engine.