diff --git a/README.rst b/README.rst index 731590eec6..431a294dff 100644 --- a/README.rst +++ b/README.rst @@ -8,211 +8,5 @@ made up of individual project repositories sharing a Launchpad group and a version number history. Many deliverables will only have one constituent project. -Requesting a Release -==================== - -The PTL or release liaison for a project may request a release from -master by submitting a patch to this repository, adding the necessary -release metadata to the file describing the deliverable to be -released. The release team will review the request and provide -feedback about the version number. - -The stable maintenance team, PTL, or release liaison for a project may -request a release from a stable branch by submitting a patch to this -repository, adding the necessary release metadata to the file -describing the deliverable to be released. The release team will -review the request and provide feedback about the version number. If -the stable release is requested by the stable maintenance team, it -should be acknowledged by the PTL or release liaison to ensure that -the development team is aware of the coming change. - -Reviewing a Release Request ---------------------------- - -Care needs to be taken when reviewing a release request such that the version -proposed (1) follows semver rules and (2) will not cause issues between -branches, particularly stable branches (at least stable branches that are not -yet using upper-constraints checking in CI runs, which is anything before -stable/liberty). - -General notes when reviewing a release request: - -* Make sure you follow semantic versioning rules `semver `_ - when picking the version number. In particular, if there is a change going - into this release which requires a higher minimum version of a dependency, - then the **minor** version should be incremented. - - .. note:: The exception to this rule is when the versions of a project are - pinned between minor versions in stable branches. In those cases we - frequently release global-requirements syncs with a patch version to fix - the target branch, e.g. stable/juno, but don't increment the minor version - to avoid it being used in a different branch, like stable/kilo. - Someone from the - `stable-maint-core `_ - team should +1 a change like this before it's approved. - -The following rules apply mostly to stable branches and therefore a member of -the `stable-maint-core `_ -team should +1 the following types of changes before they are approved. - -* For libraries, check global-requirements.txt (g-r) in the - `openstack/requirements repo `_ - to make sure the version you are about to release does not cause a - conflict and wedge the gate. Typically this is only a concern on stable - branches with (un)capped dependencies. - - Typical examples of this kind of break (before upper-constraints are used): - - #. A stable branch, for example stable/juno, has uncapped dependencies on a - library and a version is released on a newer branch, e.g. stable/kilo, - and that version has updated requirements from global-requirements in - stable/kilo which conflict with the versions of libraries allowed in - stable/juno. This then leads to ContextualVersionConflict failures when - installing packages on stable/juno. - #. Similar to the point above, but if there are overlapping version ranges - between two branches, like stable/juno and stable/kilo, you can have the - same kinds of issues where a release from one branch which has g-r syncs - specific to that branch gets used in the other branch and things break. - We saw this happen with oslo.utils 1.4.1 which was intended for - stable/juno consumption but because stable/kilo g-r allowed that version, - we broke stable/kilo CI jobs since 1.4.1 had juno-level dependencies. - -* The rule of thumb is that branches should not overlap versions at the minor - version range. For example, stable/juno can require foo>=1.1,<1.2 and - stable/kilo can require foo>=1.2,<1.3. In this way only patch-level versions - are released for foo on stable/juno and stable/kilo. The pin at the minor - version range prevents those patch-level versions from breaking each other's - branch. - -Release Approval -================ - -Releases will only be denied during periods where there are known gate -issues, or when releasing will introduce unwanted -instability. Releases made late in a week may be delayed until early -in the next week unless there is a pressing need such as a gate -failure or security issue. - -Who is Responsible for the Release? -=================================== - -The release team is responsible for helping to clearly signal the -nature of the changes in the release through good version number -selection. - -The project team is responsible for understanding the implications for -consuming projects when a new release is made, and ensuring that -releases do not break other projects. When breaks occur, the project -team is responsible for taking the necessary corrective action. - -Deliverable Files -================= - -For deliverable set of projects, we use one YAML file per release -series to hold all of the metadata for all releases of that -deliverable. For each release, we need to track: - -* the launchpad project name (such as ``oslo.config``) -* the series (Kilo, Liberty, etc.) -* for each repository - - * the name (such as ``openstack/oslo.config``) - * the hash of the commit to be tagged - -* the version number to use -* highlights for the release notes email (optional) - -We track this metadata for the history of all releases of the -deliverable, so we can render a set of release history documentation. - -The file should be named based on the deliverable to be tagged, so -releases for ``liberty`` from the ``openstack/oslo.config`` repository -will have a file in ``openstack/releases`` called -``deliverables/liberty/oslo.config.yaml``. Releases of the same deliverable from -the ``stable/kilo`` branch will be described by -``deliverables/kilo/oslo.config.yaml``. - -Deliverables File Schema -======================== - -The top level of a deliverable file is a mapping with keys: - -``launchpad`` - The slug name of the launchpad project, suitable for use in URLs. - -``releases`` - A list of the releases for the deliverable. - -Each `release` entry is a mapping with keys: - -``version`` - The version tag for that release, to be applied to all of the member - projects. - -``projects`` - A list of all of the projects making up the deliverable for that - release. - -``highlights`` - An optional message to be included in the release note email - announcing the release. (Use ``|`` to indicate a multi-line, - pre-formatted message.) - -Each `project` entry is a mapping with keys: - -``repo`` - The name of the repository on git.openstack.org. - -``hash`` - The SHA1 hash for the commit to receive the version tag. - -Examples -======== - -For example, one version of -``deliverables/liberty/oslo.config.yaml`` might contain:: - - --- - launchpad: oslo.config - releases: - - version: 1.12.0 - projects: - - repo: openstack/oslo.config - hash: 02a86d2eefeda5144ea8c39657aed24b8b0c9a39 - -and then for the subsequent release it would be updated to contain:: - - --- - launchpad: oslo.config - releases: - - version: 1.12.0 - projects: - - repo: openstack/oslo.config - hash: 02a86d2eefeda5144ea8c39657aed24b8b0c9a39 - - version: 1.12.1 - projects: - - repo: openstack/oslo.config - hash: 0c9113f68285f7b55ca01f0bbb5ce6cddada5023 - highlights: | - This release includes the change to stop importing - from the 'oslo' namespace package. - -For deliverables with multiple repositories, the list of projects -would contain all of them. For example, the Neutron deliverable might -be described by ``deliverables/liberty/neutron.yaml`` containing: - -:: - - --- - launchpad: neutron - releases: - - version: 7.0.0 - projects: - - repo: openstack/neutron - hash: somethingunique - - repo: openstack/neutron-fwaas - hash: somethingunique - - repo: openstack/neutron-lbaas - hash: somethingunique - - repo: openstack/neutron-vpnaas - hash: somethingunique +Refer to doc/source/instructions for details about how to submit +requests. diff --git a/doc/source/index.rst b/doc/source/index.rst index 10135a43df..3a9e215912 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -2,6 +2,9 @@ OpenStack Releases ==================== +Release Series +============== + .. list-table:: :header-rows: 1 @@ -32,7 +35,6 @@ - * :doc:`releases/austin` * Deprecated - .. toctree:: :glob: :maxdepth: 1 @@ -50,3 +52,10 @@ releases/cactus releases/bexar releases/austin + +Instructions +============ + +.. toctree:: + + instructions diff --git a/doc/source/instructions.rst b/doc/source/instructions.rst new file mode 100644 index 0000000000..7b7ca0ac21 --- /dev/null +++ b/doc/source/instructions.rst @@ -0,0 +1,212 @@ +======================= + Using This Repository +======================= + +Requesting a Release +==================== + +The PTL or release liaison for a project may request a release from +master by submitting a patch to this repository, adding the necessary +release metadata to the file describing the deliverable to be +released. The release team will review the request and provide +feedback about the version number. + +The stable maintenance team, PTL, or release liaison for a project may +request a release from a stable branch by submitting a patch to this +repository, adding the necessary release metadata to the file +describing the deliverable to be released. The release team will +review the request and provide feedback about the version number. If +the stable release is requested by the stable maintenance team, it +should be acknowledged by the PTL or release liaison to ensure that +the development team is aware of the coming change. + +Reviewing a Release Request +--------------------------- + +Care needs to be taken when reviewing a release request such that the version +proposed (1) follows semver rules and (2) will not cause issues between +branches, particularly stable branches (at least stable branches that are not +yet using upper-constraints checking in CI runs, which is anything before +stable/liberty). + +General notes when reviewing a release request: + +* Make sure you follow semantic versioning rules `semver `_ + when picking the version number. In particular, if there is a change going + into this release which requires a higher minimum version of a dependency, + then the **minor** version should be incremented. + + .. note:: The exception to this rule is when the versions of a project are + pinned between minor versions in stable branches. In those cases we + frequently release global-requirements syncs with a patch version to fix + the target branch, e.g. stable/juno, but don't increment the minor version + to avoid it being used in a different branch, like stable/kilo. + Someone from the + `stable-maint-core `_ + team should +1 a change like this before it's approved. + +The following rules apply mostly to stable branches and therefore a member of +the `stable-maint-core `_ +team should +1 the following types of changes before they are approved. + +* For libraries, check global-requirements.txt (g-r) in the + `openstack/requirements repo `_ + to make sure the version you are about to release does not cause a + conflict and wedge the gate. Typically this is only a concern on stable + branches with (un)capped dependencies. + + Typical examples of this kind of break (before upper-constraints are used): + + #. A stable branch, for example stable/juno, has uncapped dependencies on a + library and a version is released on a newer branch, e.g. stable/kilo, + and that version has updated requirements from global-requirements in + stable/kilo which conflict with the versions of libraries allowed in + stable/juno. This then leads to ContextualVersionConflict failures when + installing packages on stable/juno. + #. Similar to the point above, but if there are overlapping version ranges + between two branches, like stable/juno and stable/kilo, you can have the + same kinds of issues where a release from one branch which has g-r syncs + specific to that branch gets used in the other branch and things break. + We saw this happen with oslo.utils 1.4.1 which was intended for + stable/juno consumption but because stable/kilo g-r allowed that version, + we broke stable/kilo CI jobs since 1.4.1 had juno-level dependencies. + +* The rule of thumb is that branches should not overlap versions at the minor + version range. For example, stable/juno can require foo>=1.1,<1.2 and + stable/kilo can require foo>=1.2,<1.3. In this way only patch-level versions + are released for foo on stable/juno and stable/kilo. The pin at the minor + version range prevents those patch-level versions from breaking each other's + branch. + +Release Approval +================ + +Releases will only be denied during periods where there are known gate +issues, or when releasing will introduce unwanted +instability. Releases made late in a week may be delayed until early +in the next week unless there is a pressing need such as a gate +failure or security issue. + +Who is Responsible for the Release? +=================================== + +The release team is responsible for helping to clearly signal the +nature of the changes in the release through good version number +selection. + +The project team is responsible for understanding the implications for +consuming projects when a new release is made, and ensuring that +releases do not break other projects. When breaks occur, the project +team is responsible for taking the necessary corrective action. + +Deliverable Files +================= + +For deliverable set of projects, we use one YAML file per release +series to hold all of the metadata for all releases of that +deliverable. For each release, we need to track: + +* the launchpad project name (such as ``oslo.config``) +* the series (Kilo, Liberty, etc.) +* for each repository + + * the name (such as ``openstack/oslo.config``) + * the hash of the commit to be tagged + +* the version number to use +* highlights for the release notes email (optional) + +We track this metadata for the history of all releases of the +deliverable, so we can render a set of release history documentation. + +The file should be named based on the deliverable to be tagged, so +releases for ``liberty`` from the ``openstack/oslo.config`` repository +will have a file in ``openstack/releases`` called +``deliverables/liberty/oslo.config.yaml``. Releases of the same deliverable from +the ``stable/kilo`` branch will be described by +``deliverables/kilo/oslo.config.yaml``. + +Deliverables File Schema +======================== + +The top level of a deliverable file is a mapping with keys: + +``launchpad`` + The slug name of the launchpad project, suitable for use in URLs. + +``releases`` + A list of the releases for the deliverable. + +Each `release` entry is a mapping with keys: + +``version`` + The version tag for that release, to be applied to all of the member + projects. + +``projects`` + A list of all of the projects making up the deliverable for that + release. + +``highlights`` + An optional message to be included in the release note email + announcing the release. (Use ``|`` to indicate a multi-line, + pre-formatted message.) + +Each `project` entry is a mapping with keys: + +``repo`` + The name of the repository on git.openstack.org. + +``hash`` + The SHA1 hash for the commit to receive the version tag. + +Examples +======== + +For example, one version of +``deliverables/liberty/oslo.config.yaml`` might contain:: + + --- + launchpad: oslo.config + releases: + - version: 1.12.0 + projects: + - repo: openstack/oslo.config + hash: 02a86d2eefeda5144ea8c39657aed24b8b0c9a39 + +and then for the subsequent release it would be updated to contain:: + + --- + launchpad: oslo.config + releases: + - version: 1.12.0 + projects: + - repo: openstack/oslo.config + hash: 02a86d2eefeda5144ea8c39657aed24b8b0c9a39 + - version: 1.12.1 + projects: + - repo: openstack/oslo.config + hash: 0c9113f68285f7b55ca01f0bbb5ce6cddada5023 + highlights: | + This release includes the change to stop importing + from the 'oslo' namespace package. + +For deliverables with multiple repositories, the list of projects +would contain all of them. For example, the Neutron deliverable might +be described by ``deliverables/liberty/neutron.yaml`` containing: + +:: + + --- + launchpad: neutron + releases: + - version: 7.0.0 + projects: + - repo: openstack/neutron + hash: somethingunique + - repo: openstack/neutron-fwaas + hash: somethingunique + - repo: openstack/neutron-lbaas + hash: somethingunique + - repo: openstack/neutron-vpnaas + hash: somethingunique