From 5b8be82112132d05327bfffc94f4b7ca6d26723b Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 15 Mar 2019 10:13:32 -0600 Subject: [PATCH] Inst and dev guide versioning: current/latest These changes implement the versioning scheme for Installation and Developer Guides for StarlingX. These guides are release-specific. Consequently, we need to make archived, current, and latest versions of the manuals available as StarlingX releases evolve. We implemented a two-fold directory structure to keep the "current" and "latest" versions of the manuals in the forefront. "Current" indicates the newest, officially released version. "Latest" indicates the current+1 release (i.e. the release under development). Aside from "current" and "latest", the list of archived versions will grow by one with each release. Changes involved the following: * Establishing "current" and "latest" directories from what existed. * Updating of intro material and links to be appropriate for either "current" or "latest". * Update of the writer instructions for adding a new release of the install and developer manuals. material to reflect the folder's new name. * Change-Id: I37eee44c31202ac391deebec3348f1e305dbd5ab Signed-off-by: Scott Rifenbark --- .../{2018_10 => current}/index.rst | 8 +- doc/source/developer_guide/index.rst | 27 ++++-- doc/source/developer_guide/latest/index.rst | 8 +- .../controller_storage.rst | 0 .../dedicated_storage.rst | 0 .../deployment_terminology.rst | 0 .../{2018_10 => current}/duplex.rst | 0 ...-deployment-options-controller-storage.png | Bin ...x-deployment-options-dedicated-storage.png | Bin ...ngx-deployment-options-duplex-extended.png | Bin .../starlingx-deployment-options-duplex.png | Bin .../starlingx-deployment-options-simplex.png | Bin .../{2018_10 => current}/index.rst | 19 ++-- .../installation_libvirt_qemu.rst | 8 +- .../{2018_10 => current}/simplex.rst | 0 doc/source/installation_guide/index.rst | 89 ++++++++++++------ .../installation_guide/latest/index.rst | 10 +- 17 files changed, 106 insertions(+), 63 deletions(-) rename doc/source/developer_guide/{2018_10 => current}/index.rst (96%) rename doc/source/installation_guide/{2018_10 => current}/controller_storage.rst (100%) rename doc/source/installation_guide/{2018_10 => current}/dedicated_storage.rst (100%) rename doc/source/installation_guide/{2018_10 => current}/deployment_terminology.rst (100%) rename doc/source/installation_guide/{2018_10 => current}/duplex.rst (100%) rename doc/source/installation_guide/{2018_10 => current}/figures/starlingx-deployment-options-controller-storage.png (100%) rename doc/source/installation_guide/{2018_10 => current}/figures/starlingx-deployment-options-dedicated-storage.png (100%) rename doc/source/installation_guide/{2018_10 => current}/figures/starlingx-deployment-options-duplex-extended.png (100%) rename doc/source/installation_guide/{2018_10 => current}/figures/starlingx-deployment-options-duplex.png (100%) rename doc/source/installation_guide/{2018_10 => current}/figures/starlingx-deployment-options-simplex.png (100%) rename doc/source/installation_guide/{2018_10 => current}/index.rst (88%) rename doc/source/installation_guide/{2018_10 => current}/installation_libvirt_qemu.rst (92%) rename doc/source/installation_guide/{2018_10 => current}/simplex.rst (100%) diff --git a/doc/source/developer_guide/2018_10/index.rst b/doc/source/developer_guide/current/index.rst similarity index 96% rename from doc/source/developer_guide/2018_10/index.rst rename to doc/source/developer_guide/current/index.rst index 16628792a..f1708c263 100644 --- a/doc/source/developer_guide/2018_10/index.rst +++ b/doc/source/developer_guide/current/index.rst @@ -3,10 +3,10 @@ Developer guide stx.2018.10 =========================== This section contains the steps for building a StarlingX ISO from -the stx.2018.10 branch. - -If a developer guide is needed for a previous release, review the -:doc:`developer guides for all previous releases `. +the "current" StarlingX software (i.e. the most recently released version). +If this is not the software you want to use, see the +:doc:`available developer guides ` for +StarlingX. ------------ Requirements diff --git a/doc/source/developer_guide/index.rst b/doc/source/developer_guide/index.rst index 22eefd12c..3e2012a7f 100644 --- a/doc/source/developer_guide/index.rst +++ b/doc/source/developer_guide/index.rst @@ -2,15 +2,24 @@ Developer guides ================ -Developer guides for StarlingX are release specific. To build a -StarlingX ISO from the latest release, use the -:doc:`/developer_guide/2018_10/index`. +Developer guides for StarlingX are release-specific. +The following list provides help on choosing the correct +developer guide based on a release: -To build an ISO from a previous release of StarlingX, use the -developer guide for your specific release: +- The "current" release is the most recent offically released version of StarlingX. + To build a StarlingX ISO from the current release, use the :doc:`/developer_guide/current/index`. -.. toctree:: - :maxdepth: 1 +- The "latest" release is the forthcoming version under development. + To build a StarlingX ISO using the latest release, use the :doc:`/developer_guide/latest/index`. + +- Following are all available developer guides for StarlingX: + + .. toctree:: + :maxdepth: 1 + + /developer_guide/current/index + /developer_guide/latest/index + +.. When a new release of developer guides occurs, follow the steps in the + commented block of the /installation_guide/index.rst file. - /developer_guide/latest/index - /developer_guide/2018_10/index diff --git a/doc/source/developer_guide/latest/index.rst b/doc/source/developer_guide/latest/index.rst index 4c4f458e9..38fe2f9b5 100644 --- a/doc/source/developer_guide/latest/index.rst +++ b/doc/source/developer_guide/latest/index.rst @@ -3,10 +3,10 @@ Developer guide stx.2019.05 =========================== This section contains the steps for building a StarlingX ISO from -the stx.2019.05 branch. - -If a developer guide is needed for a previous release, review the -:doc:`developer guides for all previous releases `. +the "latest" StarlingX software (i.e. the "under development" branch). +If this is not the software you want to use, see the +:doc:`available developer guides ` for +StarlingX. ------------ Requirements diff --git a/doc/source/installation_guide/2018_10/controller_storage.rst b/doc/source/installation_guide/current/controller_storage.rst similarity index 100% rename from doc/source/installation_guide/2018_10/controller_storage.rst rename to doc/source/installation_guide/current/controller_storage.rst diff --git a/doc/source/installation_guide/2018_10/dedicated_storage.rst b/doc/source/installation_guide/current/dedicated_storage.rst similarity index 100% rename from doc/source/installation_guide/2018_10/dedicated_storage.rst rename to doc/source/installation_guide/current/dedicated_storage.rst diff --git a/doc/source/installation_guide/2018_10/deployment_terminology.rst b/doc/source/installation_guide/current/deployment_terminology.rst similarity index 100% rename from doc/source/installation_guide/2018_10/deployment_terminology.rst rename to doc/source/installation_guide/current/deployment_terminology.rst diff --git a/doc/source/installation_guide/2018_10/duplex.rst b/doc/source/installation_guide/current/duplex.rst similarity index 100% rename from doc/source/installation_guide/2018_10/duplex.rst rename to doc/source/installation_guide/current/duplex.rst diff --git a/doc/source/installation_guide/2018_10/figures/starlingx-deployment-options-controller-storage.png b/doc/source/installation_guide/current/figures/starlingx-deployment-options-controller-storage.png similarity index 100% rename from doc/source/installation_guide/2018_10/figures/starlingx-deployment-options-controller-storage.png rename to doc/source/installation_guide/current/figures/starlingx-deployment-options-controller-storage.png diff --git a/doc/source/installation_guide/2018_10/figures/starlingx-deployment-options-dedicated-storage.png b/doc/source/installation_guide/current/figures/starlingx-deployment-options-dedicated-storage.png similarity index 100% rename from doc/source/installation_guide/2018_10/figures/starlingx-deployment-options-dedicated-storage.png rename to doc/source/installation_guide/current/figures/starlingx-deployment-options-dedicated-storage.png diff --git a/doc/source/installation_guide/2018_10/figures/starlingx-deployment-options-duplex-extended.png b/doc/source/installation_guide/current/figures/starlingx-deployment-options-duplex-extended.png similarity index 100% rename from doc/source/installation_guide/2018_10/figures/starlingx-deployment-options-duplex-extended.png rename to doc/source/installation_guide/current/figures/starlingx-deployment-options-duplex-extended.png diff --git a/doc/source/installation_guide/2018_10/figures/starlingx-deployment-options-duplex.png b/doc/source/installation_guide/current/figures/starlingx-deployment-options-duplex.png similarity index 100% rename from doc/source/installation_guide/2018_10/figures/starlingx-deployment-options-duplex.png rename to doc/source/installation_guide/current/figures/starlingx-deployment-options-duplex.png diff --git a/doc/source/installation_guide/2018_10/figures/starlingx-deployment-options-simplex.png b/doc/source/installation_guide/current/figures/starlingx-deployment-options-simplex.png similarity index 100% rename from doc/source/installation_guide/2018_10/figures/starlingx-deployment-options-simplex.png rename to doc/source/installation_guide/current/figures/starlingx-deployment-options-simplex.png diff --git a/doc/source/installation_guide/2018_10/index.rst b/doc/source/installation_guide/current/index.rst similarity index 88% rename from doc/source/installation_guide/2018_10/index.rst rename to doc/source/installation_guide/current/index.rst index 57ee6d119..6417c1cc6 100644 --- a/doc/source/installation_guide/2018_10/index.rst +++ b/doc/source/installation_guide/current/index.rst @@ -2,9 +2,10 @@ Installation guide stx.2018.10 ============================== -This is the installation guide for release stx.2018.10. If an installation -guide is needed for a previous release, review the -:doc:`installation guides for previous releases `. +This is the installation guide for the "current" StarlingX software +(i.e. the most recently released version). +If this is not the installation guide you want to use, see the +:doc:`available installation guides `. ------------ Introduction @@ -19,7 +20,7 @@ StarlingX may be installed in: StarlingX installed in virtual environments has two options: -- :doc:`Libvirt/QEMU ` +- :doc:`Libvirt/QEMU ` - VirtualBox ------------ @@ -242,7 +243,7 @@ Unload firewall and disable firewall on boot: Getting the StarlingX ISO image ------------------------------- -Follow the instructions from the :doc:`/developer_guide/2018_10/index` to build a +Follow the instructions from the :doc:`/developer_guide/current/index` to build a StarlingX ISO image. ********** @@ -270,13 +271,13 @@ Deployment options - Standard controller - - :doc:`StarlingX Cloud with Dedicated Storage ` - - :doc:`StarlingX Cloud with Controller Storage ` + - :doc:`StarlingX Cloud with Dedicated Storage ` + - :doc:`StarlingX Cloud with Controller Storage ` - All-in-one - - :doc:`StarlingX Cloud Duplex ` - - :doc:`StarlingX Cloud Simplex ` + - :doc:`StarlingX Cloud Duplex ` + - :doc:`StarlingX Cloud Simplex ` .. toctree:: :hidden: diff --git a/doc/source/installation_guide/2018_10/installation_libvirt_qemu.rst b/doc/source/installation_guide/current/installation_libvirt_qemu.rst similarity index 92% rename from doc/source/installation_guide/2018_10/installation_libvirt_qemu.rst rename to doc/source/installation_guide/current/installation_libvirt_qemu.rst index 5caf027b7..f045a8c21 100644 --- a/doc/source/installation_guide/2018_10/installation_libvirt_qemu.rst +++ b/doc/source/installation_guide/current/installation_libvirt_qemu.rst @@ -195,10 +195,10 @@ controller-0 step. - Standard controller - - :doc:`StarlingX Cloud with Dedicated Storage Virtual Environment ` - - :doc:`StarlingX Cloud with Controller Storage Virtual Environment ` + - :doc:`StarlingX Cloud with Dedicated Storage Virtual Environment ` + - :doc:`StarlingX Cloud with Controller Storage Virtual Environment ` - All-in-one - - :doc:`StarlingX Cloud Duplex Virtual Environment ` - - :doc:`StarlingX Cloud Simplex Virtual Environment ` + - :doc:`StarlingX Cloud Duplex Virtual Environment ` + - :doc:`StarlingX Cloud Simplex Virtual Environment ` diff --git a/doc/source/installation_guide/2018_10/simplex.rst b/doc/source/installation_guide/current/simplex.rst similarity index 100% rename from doc/source/installation_guide/2018_10/simplex.rst rename to doc/source/installation_guide/current/simplex.rst diff --git a/doc/source/installation_guide/index.rst b/doc/source/installation_guide/index.rst index d8a1a0ad1..7b7382d77 100644 --- a/doc/source/installation_guide/index.rst +++ b/doc/source/installation_guide/index.rst @@ -2,37 +2,68 @@ Installation guides =================== -Installation steps for StarlingX are release specific. To install the -latest release of StarlingX, use the :doc:`/installation_guide/2018_10/index`. +Installation steps for StarlingX are release-specific. +The following list provides help on choosing the correct installation steps: -To install a previous release of StarlingX, use the installation guide -for your specific release: +- The "current" release is the most recent offically released version of StarlingX. + To install the current release of StarlingX, use the :doc:`/installation_guide/current/index`. -.. toctree:: - :maxdepth: 1 +- The "latest" release is the forthcoming version under development. + To install the latest release of StarlingX, use the :doc:`/installation_guide/latest/index`. - /installation_guide/latest/index - /installation_guide/2018_10/index +- Following are all available installation steps for StarlingX: -.. How to add a new release (installer and developer guides): - 1. Archive previous release - 1. Rename old 'latest' folder to the release name e.g. Year_Month - 2. Update links in old 'latest' to use new path e.g. - :doc:`Libvirt/QEMU ` + .. toctree:: + :maxdepth: 1 + + /installation_guide/current/index + /installation_guide/latest/index + + +.. Steps you must take when a new release of the installer and developer guides occurs: + +.. 1. Archive the "current" release: + 1. Rename the "current" folder to the release name using the convention (e.g. 2018_10). + 2. Get inside your new folder (i.e. the old "current" folder) and update all links in the *.rst + files to use the new path (e.g. :doc:`Libvirt/QEMU ` becomes - :doc:`Libvirt/QEMU ` - 2. Add new release - 1. Add a new 'latest' dir and add the new version - likely this will be a copy of the previous version, with updates applied - 2. Make sure the new files have the correct version in the page title and intro sentence e.g. '2018.10.rc1 Installation Guide' - 3. Make sure all files in new 'latest' link to the correct versions of supporting docs (do this via doc link, so that it goes to top of page e.g. :doc:`/installation_guide/latest/index`) - 4. Make sure the new release index is labeled with the correct version name e.g - .. _index-2019-05: - 3. Add the archived version to the toctree on this page - 4. If adding a new version *before* it is available (e.g. to begin work on new docs), - make sure page text still directs user to the *actual* current release, not the - future-not-yet-released version. - 5. When the release is *actually* available, make sure to update these pages: - - index - - installation guide - - developer guide - - release notes + :doc:`Libvirt/QEMU /installation_libvirt_qemu>` + 3. You might want to change your working directory to / and use Git to grep for + the "current" string (i.e. 'git grep "current" *'). For each applicable occurence, make + the call whether or not to convert the string to the actual archived string "". + Be sure to scrub all files for the "current" string in both the "installation_guide" + and "developer_guide" folders downward. + 2. Add the new "current" release: + 1. Rename the existing "latest" folders to "current". This assumes that "latest" represented + the under-development release that just officially released. + 2. Get inside your new folder (i.e. the old "latest" folder) and update all links in the *.rst + files to use the new path (e.g. :doc:`Libvirt/QEMU ` + becomes + :doc:`Libvirt/QEMU ` + 3. You might want to change your working directory to the "current" directory and use Git to grep for + the "latest" string (i.e. 'git grep "latest" *'). For each applicable occurence, make + the call whether or not to convert the string to "current". + Be sure to scrub all files for the "latest" string in both the "installation_guide" + and "developer_guide" folders downward. + 4. Because the "current" release is now available, make sure to update these pages: + - index + - installation guide + - developer guide + - release notes + 3. Create a new "latest" release, which are the installation and developer guides under development: + 1. Copy your "current" folders and rename them "latest". + 2. Make sure the new files have the correct version in the page title and intro + sentence (e.g. '2019.10.rc1 Installation Guide'). + 3. Make sure all files in new "latest" link to the correct versions of supporting + docs. You do this through the doc link, so that it resolves to the top of the page + (e.g. :doc:`/installation_guide/latest/index`) + 4. Make sure the new release index is labeled with the correct version name + (e.g .. _index-2019-05:) + 5. Add the archived version to the toctree on this page. You want all possible versions + to build. + 6. Since you are adding a new version ("latest") *before* it is available + (e.g. to begin work on new docs), make sure page text still directs user to the + "current" release and not to the under development version of the manuals. + + + diff --git a/doc/source/installation_guide/latest/index.rst b/doc/source/installation_guide/latest/index.rst index 58d3fd0cd..25c3fa3c0 100644 --- a/doc/source/installation_guide/latest/index.rst +++ b/doc/source/installation_guide/latest/index.rst @@ -2,9 +2,11 @@ Installation guide stx.2019.05 ============================== -This is the installation guide for release stx.2019.05. If an installation -guide is needed for a previous release, review the -:doc:`installation guides for previous releases `. +This is the installation guide for the "latest" StarlingX software +(i.e. the "under development" branch). +If this is not the the installation guide you want to use, +see the +:doc:`available installation guides `. ------------ Introduction @@ -242,7 +244,7 @@ Unload firewall and disable firewall on boot: Getting the StarlingX ISO image ------------------------------- -Follow the instructions from the :doc:`/developer_guide/2018_10/index` to build a +Follow the instructions from the :doc:`/developer_guide/latest/index` to build a StarlingX ISO image. **********