Move instructions from readme to published docs
Move the bulk of the instructions to a file that is part of the documentation build so we can provide links to the HTML version. Change-Id: I0aadc4034e68b0c6bf977248fdc075f10b7b0cc4
This commit is contained in:
Doug Hellmann
parent
302737f82e
commit
7f5b643632
210
README.rst
210
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 <http://semver.org/>`_
|
||||
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 <https://review.openstack.org/#/admin/groups/530,members>`_
|
||||
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 <https://review.openstack.org/#/admin/groups/530,members>`_
|
||||
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 <http://git.openstack.org/cgit/openstack/requirements/>`_
|
||||
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.
|
||||
|
||||
@ -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
|
||||
|
||||
212
doc/source/instructions.rst
Normal file
212
doc/source/instructions.rst
Normal file
@ -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 <http://semver.org/>`_
|
||||
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 <https://review.openstack.org/#/admin/groups/530,members>`_
|
||||
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 <https://review.openstack.org/#/admin/groups/530,members>`_
|
||||
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 <http://git.openstack.org/cgit/openstack/requirements/>`_
|
||||
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
|
||||
Loading…
Reference in New Issue
Block a user