releases/doc/source/instructions.rst

=======================
 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.

#. Prepare the release request by submitting a patch to this
   repository.

   * Set the first line (summary) of the commit message to the package
     name and version being requested.

   * If you are not the release liaison or PTL, have the PTL of the
     project acknowledge the request with a +1.

#. Prepare an update to the openstack/requirements repository to
   change upper-constraints.txt to ensure the new release is tested in
   the gate. You may also need to update global-requirements.txt in
   the same patch for a release with new features on which a project
   depends (bug fix releases do not need the requirements
   updated). Use a ``Depends-On`` tag in the commit message to tie the
   patch to the original release request so that the requirements and
   constraints patch will not merge until the release request merges.

#. Leave a comment on the release request linking it to the
   requirements repository update.

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.

* Make sure there is a requirements update patch to enable use of the
  new release. With the constraints system in place, releasing a
  library is no longer sufficient to cause it to be used in the CI
  systems. We must explicitly update the constraints file for
  integration tests, and we want to ensure that the lower bounds
  accurately reflect the versions needed to provide features for the
  consuming applications. This latter step is difficult to do
  accurately via a script, so we need it to be done by the person
  releasing the library.

* Make sure the summary of the patch includes the deliverable name and
  version number.

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