Jump to: navigation, search

Difference between revisions of "Documentation/Release"

Line 28: Line 28:
  
 
Here are the checklist steps for creating a release of the Documentation from the http://github.com/openstack/openstack-manuals repository.
 
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:
 
Create a local branch that will become the stable/releasename branch. Then, do all these things to it:
 
= Actions on Final Branch =
 
  
 
# Change all pom.xml files:
 
# Change all pom.xml files:

Revision as of 23:46, 15 November 2015

Overview

The first release activity is to start testing on the Install Guide, because this takes the longest time. It depends on getting packages from the various distros, and finding people willing to test the guide against those packages. We won't publish the Install Guide for a particular distro until we're satisfied that it has been thoroughly and successfully tested. During this time, we limit the patches we will accept against the install guide to ensure only critical changes go in (this helps to avoid having the guide change while it's being tested).

During this time, we also work on release notes. These are largely compiled by the PTL or CPL of the project team involved, but we are responsible for reviewing and copyediting.

On the days immediately before release day, and on release day itself, we do the infra tasks required to update the front page of docs.openstack.org to reflect the new release name and docs. After that, we keep publishing to Master until the branch is cut, which happens a couple of weeks after the actual release day (usually shortly after Summit).

Timeline

  • When testing opens: Ping CPLs to check their chapters, ping packagers to check on availability.
  • Two weeks before release: Release notes
  • 12-24 hours before release day: https://wiki.openstack.org/wiki/Documentation/Release
  • On release day: Change the front page so the new release is the default.
  • After release day (usually a couple of weeks): cut the branch for Install Guide and Config Ref

Testing the Install Guide

Updating the Config Ref

Release Notes

Infra tasks

Cut the release branch

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.

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

  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 Kilo release, use 2.1.4. 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/juno only:
  openstack-doc-test --check-build --publish --only-book install-guide --only-book config-reference --verbose

Also, create a branch on our translation server and take care that translations for Install Guide are setup for this.

Retire old release branches

Before retiring a branch, add an "unmainted notice" to the guides that are published from the branch and publish these guides

Updating Google

Update Google site map and Google Custom Search Engine

  • Build a sitemap using openstack-doc-tools.
  • Ensure that the sitemap.xml stored on the web server contains links to the latest release.
  • Ensure that the most recently End-Of-Life release is not listed in sitemap.xml, by deleting the content and adding a redirect to the root / of the site.