Icehouse release for training guides

https://blueprints.launchpad.net/openstack-training-guides/+spec/training-icehouse-release

Training guides is ready to release Icehouse content. As per our discussions during the Kilo design sessions in Paris, the team came to a common conclusion to transition from XML books to RST presentations for delivering training content more efficiently and to eliminate duplication of the content.

Advantages:

  • Easy to transition from XML to RST.
  • XML content will still be accessible for the current training sessions.
  • Repetition of content from the manuals repository will be eliminated.
  • Easier to get in track with the current release cycle of OpenStack.
  • Maintain release cycle in sync with OpenStack releases.

Note: Etherpad discussions for Kilo summit: https://etherpad.openstack.org/p/training-guides-kilo-summit

Problem description

A detailed description of the problem:

  • XML content is to be archived and deleted.
  • Migrate from XML book format to RST presentation format.
  • Keep the existing content for supporting on-going training sessions.
  • Publish current XML content to Icehouse branch only.
  • Other releases like Juno, Kilo will be published using RST based slides.
  • In future Juno, Kilo branches will be created as required for publishing the newer releases for training guides.

Proposed change

  • Freeze the master branch and branch it for Icehouse.
  • Add Icehouse watermark to the XML content.
  • The XML content will reside in the Icehouse branch for training guides.
  • XML content will not be under active development and mostly for archival purposes for supporting ongoing training sessions using the current content.
  • There will be no XML content in the master branch after the release.
  • Master branch will only contain RST files.

Alternatives

  • Use git history to point to the given Icehouse release instead of branch. This has multiple issues: - It may create confusion for trainers (our end-users). - This will only serve the developers of this project. - Difficult to publish newer releases.
  • Keep XML and RST files side by side. - This alternative is not advisable as it has multiple issues with XML cross-referencing and should be avoided at all costs.

Implementation

Assignee(s)

dguitarbite

Work Items

  • Freeze master branch for training guides repository.
  • Create a stable/icehouse branch based on the current master branch.
  • Update docs.openstack.org/icehouse/index.html page to point to /icehouse/training-guides/.
  • Change publish process in icehouse branch (pom.xml, tox.ini) in the stable/icehouse branch.
  • Remove XML content from openstack/training-guides master repo.
  • Add redirects from docs.openstack.org/training-guides/ to docs.openstack.org/icehouse/training-guides.
  • Change publish process in master branch to publish to docs.openstack.org/trunk/training-guides which include build results of RST source content.
  • Update docs.openstack.org/trunk/index.html page in master branch to link to build results of the RST content.

Dependencies

None.

Testing