Icehouse release for training guides¶
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.
- 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
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.
- 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.
- 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.
- 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.