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 <srifenbark@gmail.com>

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 </developer_guide/index>`.
+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 </developer_guide/index>` for
+StarlingX.
 
 ------------
 Requirements

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

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 </developer_guide/index>`.
+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 </developer_guide/index>` for
+StarlingX.
 
 ------------
 Requirements

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 </installation_guide/index>`.
+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 </installation_guide/index>`.
 
 ------------
 Introduction
@@ -19,7 +20,7 @@ StarlingX may be installed in:
 
 StarlingX installed in virtual environments has two options:
 
-- :doc:`Libvirt/QEMU </installation_guide/2018_10/installation_libvirt_qemu>`
+- :doc:`Libvirt/QEMU </installation_guide/current/installation_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 </installation_guide/2018_10/dedicated_storage>`
-   - :doc:`StarlingX Cloud with Controller Storage </installation_guide/2018_10/controller_storage>`
+   - :doc:`StarlingX Cloud with Dedicated Storage </installation_guide/current/dedicated_storage>`
+   - :doc:`StarlingX Cloud with Controller Storage </installation_guide/current/controller_storage>`
 
 -  All-in-one
 
-   - :doc:`StarlingX Cloud Duplex </installation_guide/2018_10/duplex>`
-   - :doc:`StarlingX Cloud Simplex </installation_guide/2018_10/simplex>`
+   - :doc:`StarlingX Cloud Duplex </installation_guide/current/duplex>`
+   - :doc:`StarlingX Cloud Simplex </installation_guide/current/simplex>`
 
 .. toctree::
    :hidden:

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 </installation_guide/2018_10/dedicated_storage>`
-   - :doc:`StarlingX Cloud with Controller Storage Virtual Environment </installation_guide/2018_10/controller_storage>`
+   - :doc:`StarlingX Cloud with Dedicated Storage Virtual Environment </installation_guide/current/dedicated_storage>`
+   - :doc:`StarlingX Cloud with Controller Storage Virtual Environment </installation_guide/current/controller_storage>`
 
 -  All-in-one
 
-   - :doc:`StarlingX Cloud Duplex Virtual Environment </installation_guide/2018_10/duplex>`
-   - :doc:`StarlingX Cloud Simplex Virtual Environment </installation_guide/2018_10/simplex>`
+   - :doc:`StarlingX Cloud Duplex Virtual Environment </installation_guide/current/duplex>`
+   - :doc:`StarlingX Cloud Simplex Virtual Environment </installation_guide/current/simplex>`

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 </installation_guide/latest/installation_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 <Year_Month> 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 </installation_guide/current/installation_libvirt_qemu>`
          becomes
-         :doc:`Libvirt/QEMU </installation_guide/2018_10/installation_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_guide/<Year_Month>/installation_libvirt_qemu>`
+         3. You might want to change your working directory to /<Year_Month> 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 "<Year_Month>".
+         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 </installation_guide/latest/installation_libvirt_qemu>`
+         becomes
+         :doc:`Libvirt/QEMU </installation_guide/current/installation_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.
+
+
+

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 </installation_guide/index>`.
+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 </installation_guide/index>`.
 
 ------------
 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.
 
 **********