From 93040e697a14032f2d38f0cf4821f8cf5b0dfade Mon Sep 17 00:00:00 2001 From: Lana Brindley Date: Wed, 5 Oct 2016 14:49:10 +1000 Subject: [PATCH] Adding new Release chapter New content on the release process for reference by PTL and release managers. blueprint: release-chapter-contrib-guide Change-Id: I0819effe5f26f234ddcd4f1d7db26470886fe441 --- doc/contributor-guide/source/index.rst | 1 + doc/contributor-guide/source/release.rst | 15 +++ .../source/release/taskdetail.rst | 121 ++++++++++++++++++ .../source/release/taskoverview.rst | 41 ++++++ 4 files changed, 178 insertions(+) create mode 100644 doc/contributor-guide/source/release.rst create mode 100644 doc/contributor-guide/source/release/taskdetail.rst create mode 100644 doc/contributor-guide/source/release/taskoverview.rst diff --git a/doc/contributor-guide/source/index.rst b/doc/contributor-guide/source/index.rst index a4b577b288..07c594ed5f 100644 --- a/doc/contributor-guide/source/index.rst +++ b/doc/contributor-guide/source/index.rst @@ -31,6 +31,7 @@ Contents docs-review.rst docs-builds.rst doc-tools.rst + release.rst Glossary ~~~~~~~~ diff --git a/doc/contributor-guide/source/release.rst b/doc/contributor-guide/source/release.rst new file mode 100644 index 0000000000..4e4cc68b0b --- /dev/null +++ b/doc/contributor-guide/source/release.rst @@ -0,0 +1,15 @@ +.. _doc-release: + +================================== +Publishing a documentation release +================================== + +This section describes the tasks that need to be completed to publish the +documentation for an OpenStack release. It is intended to be used by the +PTL and release managers. + +.. toctree:: + :maxdepth: 2 + + release/taskoverview.rst + release/taskdetail.rst diff --git a/doc/contributor-guide/source/release/taskdetail.rst b/doc/contributor-guide/source/release/taskdetail.rst new file mode 100644 index 0000000000..37d50314c5 --- /dev/null +++ b/doc/contributor-guide/source/release/taskdetail.rst @@ -0,0 +1,121 @@ +=================== +Release task detail +=================== + +This section provides detailed instructions for each release task. + +Installation Tutorial testing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The process for Installation Tutorial testing begins about six weeks before +release day. First of all, create a new testing page on the wiki, based on +`the previous one `_. + +You will need to locate pre-release packages for each distribution, and +disseminate information about obtaining the packages for testing purposes. +The current list of packaging contacts: + +* Debian: Thomas Goirand (zigo) +* openSUSE/SLES: Pranav Salunke (dguitarbite) +* RDO/CentOS: Petr Kovar and Haïkel Guémar +* Ubuntu: James Page + +As soon as pre-release packages are available, you can start testing. Testers +should look at the current draft version of the document, and attempt to +run each command on the pre-release package. If you are able to run the +instructions in the book successfully, then place a green tick in the +matrix, noting which version you tested against. If a command can't be run, +and it's confirmed to be a bug in the documentation, add a note in the +`Issues` section, so that the book can be updated. + +.. note:: + + Testers should avoid raising bugs against the book at this stage, to ensure + that the fix lands before release. Instead, list the details on the testing + wiki page, so other testers are aware of it. + +It is also important to ask Cross Project Liaisons (CPLs) to check the +chapters or project-specific guides that relate to their projects. It is +possible that changes might that have happened within projects during the +release that have not been reflected in the documentation. + +As release day draws near, and testing progresses, the PTL will make a +judgement call on whether or not the various Installation Tutorials are +tested sufficiently to be released. In some rare cases, the book either +has not been tested adequately, or has performed badly in tests, which can +justify not publishing that book. In this case, the PTL will contact +relevant parties to let them know of the decision, and work with them to +get the book to an adequate level to be published at some point after +release day. + +Release Notes +~~~~~~~~~~~~~ + +OpenStack Manuals no longer handles release notes for the project teams. +However, we do need to write release notes for our documentation. Release +notes should be added as major changes occur throughout the release, however +this is often overlooked - both by authors and reviewers - and thus a final +review is needed to check that all major changes are in. Contact each +Speciality Team lead, listed at :doc:`../team-structure`., and ask them for +the notes for the books they look after. The source repository for release +notes is `openstack-manuals/releasenotes/source/RELEASENAME` and they are +published to +. + +Publish index page +~~~~~~~~~~~~~~~~~~ + +Create a new index page for docs.openstack.org, at +`openstack-manuals/www/RELEASENAME/index.html`, copying the existing page +for the current release, with updated release name and date. Add the new page +to the list in `openstack-manuals/www/www-index.html`. This patch should have +a core -2 review on it until it is ready to be published. This should happen +about a week before release day, sending the page live, but should remain +unlinked until the last moment. This is to allow the release team to link +to the new page. + +Update links in all books +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Every book maintained by OpenStack Manuals will need to be checked for +links referencing the old release. Do one patch per book, record the review +number in the release etherpad so that release managers can review easily. +For versioned books, these patches should have a core -2 review on them until +they are ready to be published at release time. For continuously released +books, these patches can be merged immediately. + + +Run scripts for Configuration and CLI Reference Guides +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Run scripts to pull the latest changes for the Configuration Reference and +CLI Reference Guides. Instructions for using these scripts are in the +:ref:`doc-tools` chapter. + +Update main docs page +~~~~~~~~~~~~~~~~~~~~~ + +Change the front page so the new release is the default, by synchronising +`openstack-manuals/www/RELEASENAME/index.html`, which you created earlier, +with `openstack/openstack-manuals/www/index.html`. These two files should +have the same content. You will also need to update the release version in the +dropdown header. This is the main patch that sends the release live, so it +must have a core -2 review on it until it is ready to be published. Changes to +the docs site can take an hour or more to populate, depending on the status of +the gate and the number of changes being pushed at release time, so be +prepared to have this ready well ahead of the official release time. You can +check the current gate status at +`Zuul status `_ to get an idea of the +current merge times. + +Cut the branch +~~~~~~~~~~~~~~ + +Cut the branch for versioned guides. This usually happens about a month +after release day, but the timing is informed mainly by the volume of +changes going in to the guides. + +Update sphinxmark +~~~~~~~~~~~~~~~~~ +Update the sphinxmark configuration files for versioned guides with the +latest release name. diff --git a/doc/contributor-guide/source/release/taskoverview.rst b/doc/contributor-guide/source/release/taskoverview.rst new file mode 100644 index 0000000000..c9a199e9dd --- /dev/null +++ b/doc/contributor-guide/source/release/taskoverview.rst @@ -0,0 +1,41 @@ +====================== +Release tasks overview +====================== + +This section provides an overview of the tasks that need to be completed +for a documentation release, and a rough schedule of when to complete +each task. The schedule is expressed in terms of `time before release day`. +Release day is usually 1300UTC on the `initial release date` listed on the +`release schedule `_. + +*Four to six weeks before release* + Ping packagers to locate pre-release packages to test the Installation + Tutorial against, and start looking for willing volunteers to help test. + +*Four weeks* + Ping Cross Project Liaisons (CPLs) to check their chapters, and ping + packagers to check on package availability. As soon as pre-release + packages are available, ask people to start testing. + +*Two to four weeks* + Ping Speciality Team leads to review and update release notes for + openstack-manuals. + +*One to two weeks* + Publish project-specific docs to new branch, publish index page to docs + (but leave unlinked). + +*One week* + Check and update all books to have correct version information, and update + any links in each book to refer to the new release. Run scripts to pull the + latest changes for the Configuration Reference and CLI Reference Guides. + +*On release day* + Add new release name to the dropdown menu on the docs page, regenerate the + sitemap.xml, and change the front page so the new release is the default. + +*After release day* + Cut the branch for versioned guides. This usually happens about a month + after release day, but the timing is informed mainly by the volume of + changes going in to the guides. Update the sphinxmark configuration files + for versioned guides with the latest release name.