Jump to: navigation, search

Difference between revisions of "Documentation/Release"

(Update Google site map and Google Custom Search Engine)
(Timeline)
 
(41 intermediate revisions by 4 users not shown)
Line 1: Line 1:
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.
+
= Overview =
  
At release time, have one doc contributor (or the doc lead) follows the instructions below to make a release 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).  
  
=Documentation Release=
+
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.
  
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.  
+
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).  
  
Here are the checklist steps for creating a release of the Documentation from the http://github.com/openstack/openstack-manuals repository.
+
= Timeline =
  
= Pre-requisites =
+
* Two to four weeks before testing (T-60 days): ping packagers to locate pre-release packages to test against
 +
* When testing opens (T-30 days): Ping CPLs to check their chapters, ping packagers to check on availability.
 +
* Some days before release: Publish versioned guides to /RELEASENAME and create /RELEASENAME/index.html page.
 +
* Some days before release: Add /RELEASENAME to openstackdocstheme so that it books reference it: we dropped version specific information from docstheme
 +
* Some days before release: Check and update all books to have correct version info
 +
* 12-24 hours before release day: Run docs scripts for Config Ref & CLI Ref
 +
* 12-24 hours before release day: Cut the stable branch
 +
* On release day: Change the front page so the new release is the default. (~1500UTC)
 +
* After release day (usually a couple of weeks): cut the branch for Install Guide and Config Ref
 +
* Update the sphinxmark config in the conf.py files for the Install Guide, Config Ref, and Networking Guide with the latest release name
  
Create a local branch that will become the stable/releasename branch. Then, do all these things to it:
+
= Testing the Install Guide =
  
= Actions on Final Branch =
+
*  TBD
  
# Change all pom.xml files:
+
= Updating the Config Ref =
#* 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.
 
# 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.
 
# 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.
 
# Change the index.html files in the /www folder to point to the release name version of each deliverable.
 
# Check in this final branch for review.
 
# 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.
 
  
After the branch is created, do the following:
+
The scripts need to manually run before release day to ensure we've picked up all the latest changes in the source repos.
* 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 = 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:
 
<pre>
 
commands =
 
  # Commands for stable/juno only:
 
  openstack-doc-test --check-build --publish --only-book install-guide --only-book config-reference --verbose
 
</pre>
 
  
= Update Google site map and Google Custom Search Engine =
+
= 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.
 +
 
 +
== Preparation for releasing ==
 +
* Publish the versioned guides to both /draft and /liberty, this needs adopting of the file  tools/publishdocs.sh.
 +
* Create a /liberty/index.html page
 +
* Update the menus in openstackdocstheme to include liberty - and then release openstackdocstheme in time for the release
 +
* Check manuals for release:
 +
** Update all manuals in all repos so that they link to latest version of versioned guides (to liberty version of Install Guide and Configuration Reference).
 +
** Configuration reference: Regenerate all option tables as well as the tables showing difference between releases.
 +
** Command-Line reference: Check that all client packages are documented and up-to-date.
 +
** Operations Guide: Add upgrade information for new release.
 +
** All continuously published manuals should document current release and the two previous ones, so update text on the index page saying "This guide documents the Juno, Kilo, and Liberty releases."
 +
* Final review of release notes (file RELEASENOTES.rst in openstack-manuals).
 +
 
 +
== On the day of the release ==
 +
 
 +
* Update the /index.html page so that it has the new release as current (https://review.openstack.org/233583)
 +
* Update drop-down menu on for current release (https://review.openstack.org/233582)
 +
* Update redirects in .htaccess to point to current release (https://review.openstack.org/#/c/233555)
 +
* Update the sitemap.xml files for docs.openstack.org and developer.openstack.org.
 +
 
 +
== Branch creation ==
 +
 
 +
Here are the checklist steps for creating a stable branch of the Documentation from the http://git.openstack.org/cgit/openstack/openstack-manuals/ repository.
 +
 
 +
# Ask the CI team to create a stable branch for openstack-manuals
 +
# Update file <code>gerritbot/channels.yaml</code> in repository openstack-infra/project-config for notifications of the new branch.
 +
# 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 <code>defaultbranch=stable/liberty</code> 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
 +
#* Disable syncing of files from liberty branch of openstack-manuals to other repos (https://review.openstack.org/246195)
 +
#* Move translated guides to /liberty for publishing (https://review.openstack.org/246205 )
 +
# On master, stop publishing to both /draft and /liberty, adjust tools/publishdocs.sh.
 +
# On master, change version info in versioned guides to next release (mitaka).
 +
# 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)
 +
# Enable periodic translation jobs for liberty in project-config repository (https://review.openstack.org/246201)
 +
 
 +
== Translation resource minimization ==
 +
# To minimize the translation resouces, change the common-rst generation method (https://review.openstack.org/#/c/246751/)
 +
 
 +
= Retire old release branches =
 +
 
 +
Before retiring a branch, add an "unmaintained 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.
 
* 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 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.  
 
* 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.  
* Ensure that the past release site is removed from the Google Custom Search engine.
 
  
 
----
 
----
 
[[Category:Documentation]]
 
[[Category:Documentation]]

Latest revision as of 07:23, 7 September 2016

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

  • Two to four weeks before testing (T-60 days): ping packagers to locate pre-release packages to test against
  • When testing opens (T-30 days): Ping CPLs to check their chapters, ping packagers to check on availability.
  • Some days before release: Publish versioned guides to /RELEASENAME and create /RELEASENAME/index.html page.
  • Some days before release: Add /RELEASENAME to openstackdocstheme so that it books reference it: we dropped version specific information from docstheme
  • Some days before release: Check and update all books to have correct version info
  • 12-24 hours before release day: Run docs scripts for Config Ref & CLI Ref
  • 12-24 hours before release day: Cut the stable branch
  • On release day: Change the front page so the new release is the default. (~1500UTC)
  • After release day (usually a couple of weeks): cut the branch for Install Guide and Config Ref
  • Update the sphinxmark config in the conf.py files for the Install Guide, Config Ref, and Networking Guide with the latest release name

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.

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.

Preparation for releasing

  • Publish the versioned guides to both /draft and /liberty, this needs adopting of the file tools/publishdocs.sh.
  • Create a /liberty/index.html page
  • Update the menus in openstackdocstheme to include liberty - and then release openstackdocstheme in time for the release
  • Check manuals for release:
    • Update all manuals in all repos so that they link to latest version of versioned guides (to liberty version of Install Guide and Configuration Reference).
    • Configuration reference: Regenerate all option tables as well as the tables showing difference between releases.
    • Command-Line reference: Check that all client packages are documented and up-to-date.
    • Operations Guide: Add upgrade information for new release.
    • All continuously published manuals should document current release and the two previous ones, so update text on the index page saying "This guide documents the Juno, Kilo, and Liberty releases."
  • Final review of release notes (file RELEASENOTES.rst in openstack-manuals).

On the day of the release

Branch creation

Here are the checklist steps for creating a stable branch of the Documentation from the http://git.openstack.org/cgit/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
    • Disable syncing of files from liberty branch of openstack-manuals to other repos (https://review.openstack.org/246195)
    • Move translated guides to /liberty for publishing (https://review.openstack.org/246205 )
  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)
  7. Enable periodic translation jobs for liberty in project-config repository (https://review.openstack.org/246201)

Translation resource minimization

  1. To minimize the translation resouces, change the common-rst generation method (https://review.openstack.org/#/c/246751/)

Retire old release branches

Before retiring a branch, add an "unmaintained 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.