diff --git a/doc/source/contributor/periodic-work.rst b/doc/source/contributor/periodic-work.rst index e96024dd6f..00d2cc6a56 100644 --- a/doc/source/contributor/periodic-work.rst +++ b/doc/source/contributor/periodic-work.rst @@ -7,13 +7,7 @@ Periodic Work Releasing ========= -Our release schedule for stable branches is around every two weeks: - -* 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. +Our release frequency is discussed in :ref:`reference_release`. Dependency Updates ------------------ diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst index 6a6bac99ed..5fa45df90b 100644 --- a/doc/source/reference/index.rst +++ b/doc/source/reference/index.rst @@ -22,6 +22,7 @@ see the :dev_docs:`Contributors Guide `. .. toctree:: :maxdepth: 1 + releases.rst conventions.rst inventory/inventory.rst configuration/advanced-config.rst diff --git a/doc/source/reference/releases.rst b/doc/source/reference/releases.rst new file mode 100644 index 0000000000..53321f7998 --- /dev/null +++ b/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 ``.0.0.0b`` where ```` is the next major +release number, and ```` 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 ```` 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. diff --git a/doc/source/user/source-overrides/index.rst b/doc/source/user/source-overrides/index.rst index 26b1c6fdf7..b8cf1de7bc 100644 --- a/doc/source/user/source-overrides/index.rst +++ b/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 ==============================================