Jump to: navigation, search


< Documentation
Revision as of 20:26, 16 November 2015 by Jaegerandi (talk | contribs) (Cut the stable branch)


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


  • When testing opens: Ping CPLs to check their chapters, ping packagers to check on availability.
  • Two weeks before release: Release notes
  • Some days before release: Publish versioned guides to /RELEASENAME and create /RELEASENAME/index.html page.
  • 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

  • TBD

Updating the Config Ref

The scripts need to manually run before release day to ensure we've picked up all the latest changes in the source repos.

Release Notes

They're a thing you have to do. https://wiki.openstack.org/wiki/ReleaseNotes/<releasename>

Projects to be documented:

  • barbican
  • ceilometer
  • cinder
  • designate
  • glance
  • heat
  • horizon
  • ironic
  • keystone
  • manila 
  • neutron
  • nova
  • sahara
  • swift
  • trove
  • zaqar

Cut the stable branch

Note that this description is current for liberty and uses liberty as example.

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/liberty. However, only certain documents are "released", currently those are the Installation Guides and the Configuration Reference.

Note that we initially publish the versioned guides to both /draft and /liberty, this needs adopting of the file tools/publishdocs.sh.

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

  1. Ask the CI team to create a stable branch for openstack-manuals
  2. Update file gerritbot/channels.yaml in repository openstack-infra/project-config for notifications of the new branch.
  3. After the branch is created, do the following on the branch in openstack-manuals so that git review works automatically:
    • Update the .gitreview file in openstack-manuals to add defaultbranch=stable/liberty to indicate the branch that git review will use
    • Setup building to disable all non-translated and non-versioned guides for translation, oinly build backported guides (install-guide and config-reference), and do not publish web pages (liberty patch: https://review.openstack.org/245851)
      • Update doc-test.conf to publish to publish to /liberty
      • Update doc-tools-check-languages.conf to disable unwanted translated guides
      • Update tools/build-all-rst.sh to disable publishing of unwanted guides
      • Update tools/publishdocs.sh to disable publishing of www files
      • Update tools/build-install-guides-rst.sh for publishing to /liberty
  4. On master, stop publishing to both /draft and /liberty, adjust tools/publishdocs.sh.
  5. On master, change version info in versioned guides to next release (mitaka).
  6. Create a branch on our translation server so that translators can translate the versioned guide (Install Guide for Liberty). This needs a Zanata admin (AJaeger, Daisy, Pleia2, etc)

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.