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
|
and a version number history. Many deliverables will only have one
|
||||||
constituent project.
|
constituent project.
|
||||||
|
|
||||||
Requesting a Release
|
Refer to doc/source/instructions for details about how to submit
|
||||||
====================
|
requests.
|
||||||
|
|
||||||
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
|
|
||||||
|
|||||||
@ -2,6 +2,9 @@
|
|||||||
OpenStack Releases
|
OpenStack Releases
|
||||||
====================
|
====================
|
||||||
|
|
||||||
|
Release Series
|
||||||
|
==============
|
||||||
|
|
||||||
.. list-table::
|
.. list-table::
|
||||||
:header-rows: 1
|
:header-rows: 1
|
||||||
|
|
||||||
@ -32,7 +35,6 @@
|
|||||||
- * :doc:`releases/austin`
|
- * :doc:`releases/austin`
|
||||||
* Deprecated
|
* Deprecated
|
||||||
|
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:glob:
|
:glob:
|
||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
@ -50,3 +52,10 @@
|
|||||||
releases/cactus
|
releases/cactus
|
||||||
releases/bexar
|
releases/bexar
|
||||||
releases/austin
|
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