Merge "[docs] Add reference page with release information"

doc/source/contributor/periodic-work.rst

@@ -7,13 +7,7 @@ Periodic Work
 Releasing
 =========
 
-Our release schedule for stable branches is around every two weeks:
+Our release frequency is discussed in :ref:`reference_release`.
-
-* We request an OpenStack release on the second Friday of the month
-* We request an OpenStack release on the last Friday of the month
-
-The releases take generally a few days to get "tagged" and be publicly
-available.
 
 Dependency Updates
 ------------------

doc/source/reference/index.rst

@@ -22,6 +22,7 @@ see the :dev_docs:`Contributors Guide <contributor/index.html>`.
 .. toctree::
    :maxdepth: 1
 
+   releases.rst
    conventions.rst
    inventory/inventory.rst
    configuration/advanced-config.rst

doc/source/reference/releases.rst

@@ -0,0 +1,91 @@
+.. _reference_release:
+
+========
+Releases
+========
+
+What is the OSA release model
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+OpenStack-Ansible (OSA) uses the 'cycle-trailing' release model as specified
+in the OpenStack `release model reference_`.
+
+.. _release model reference: https://releases.openstack.org/reference/release_models.html
+
+How are release tags decided?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+In order to ensure a common understanding of what release versions mean, we
+use `Semantic Versioning 2.0.0_` for versioning as a basis. The exception to
+the rule is for milestone releases during a development cycle, where releases
+are tagged ``<MAJOR>.0.0.0b<MILESTONE>`` where ``<MAJOR>`` is the next major
+release number, and ``<MILESTONE>`` is the milestone number.
+
+The OpenStack series names are alphabetical, with each letter matched to a
+number (eg: Austin = 1, Bexar = 2, Newton = 14, Pike = 16, etc). OSA adopted
+the same ``<MAJOR>`` release numbering as the Nova project to match the
+overall OpenStack series version numbering.
+
+.. _Semantic Versioning 2.0.0: https://semver.org
+
+How frequently does OSA release?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Major releases are done every six months according to the `OpenStack release
+schedule_`. Each major release is consistent with an OpenStack series.
+
+Minor/patch releases are requested for stable branches on the second and last
+Friday of every month. The releases are typically completed within a few days
+of the request.
+
+.. _OpenStack release schedule: https://releases.openstack.org
+
+What version of OpenStack is deployed by OSA?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For each OSA release, the OpenStack version that is deployed is set to a
+specific OpenStack `git SHA-1 hash_` (SHA). These are updated after every
+OSA release. The intent is to ensure that OSA users are able to enjoy an
+updated OpenStack environment with smaller increments of change than the
+typical upstream service releases allow for as they are usually very
+infrequent.
+
+This does mean that a stable OSA deployment will include a version of a
+service (eg: nova-17.0.3dev4) which does not match a tag exactly as you may
+expect (eg: nova-17.0.3).
+
+If you wish to change the SHA to a specific SHA/tag/branch, or wish to use
+your own fork of an OpenStack service, please see the section titled
+:ref:`override_openstack_sources` in the user guide.
+
+.. _git SHA-1 hash: https://git-scm.com/book/en/v2/Git-Internals-Git-Objects
+
+When does a patch to an OSA role get into a release?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For each OSA release, the Ansible roles that form that release are set to a
+specific `git SHA-1 hash_` (SHA). These are updated after every OSA release.
+
+OSA frequently does pro-active bugfix backports. In order to reduce the risk
+of these backports introducing any destabilization, OSA implements a 'soak'
+period for any patches implemented in the stable branches for roles, but also
+provides for circumventing this in exceptional circumstances.
+
+A patch merged into a role is immediately tested by other role tests,
+ensuring that any major breaking change is caught. Once a minor/patch release
+is requested, the integrated build receives a 'SHA bump' patch to update the
+integrated build to using the latest available roles including that new patch.
+This new set is available for testing to anyone wanting to use the head of the
+stable branch, and is tested in periodic tests until the next release. In
+total, that means that the cycle time for a patch from merge to release is
+anywhere from two weeks to one month.
+
+If there is a requirement to rush a role patch into the next release, then
+anyone may propose a change to the ``ansible-role-requirements.yml`` file
+in the ``openstack/openstack-ansible`` repository with the appropriate
+justification.
+
+We believe that this approach brings a balance of both reasonable stability,
+while still being able to do pro-active backports.
+
+The only exception to this rule is for the ``master`` branch, which
+intentionally consumes the ``master`` branch from all roles between releases
+so that any changes are immediately integration tested.

doc/source/user/source-overrides/index.rst

@@ -40,6 +40,8 @@ Overriding the roles
 Overriding the role file has been explained in the reference guide,
 on the :ref:`extend_osa_roles` section.
 
+.. _override_openstack_sources:
+
 Overriding other upstream projects source code
 ==============================================