move the submission guide out of the readme to the reference docs
Move the existing content for contributors wanting to propose releases out of the readme file and into the reference guide that we publish. Change-Id: Ie90e09a5dd3eeac8c66511aa4b9567402cfa8282 Signed-off-by: Doug Hellmann <doug@doughellmann.com>
This commit is contained in:
Doug Hellmann
parent
1a13da135a
commit
7bbde65789
713
README.rst
713
README.rst
@ -14,714 +14,5 @@ The repository is managed by the `Release Management team
|
||||
.. image:: https://governance.openstack.org/tc/badges/releases.svg
|
||||
:target: https://governance.openstack.org/tc/reference/tags/index.html
|
||||
|
||||
Defining a Deliverable
|
||||
======================
|
||||
|
||||
A "deliverable" is a unit of distribution of a useful project. It may
|
||||
be a single library or several server components that are packaged
|
||||
separately but released and used together. Rather than base the
|
||||
definition on technical terms such as packaging, we use the social
|
||||
organization of the project to identify deliverables. If the contents
|
||||
of two repositories share a bug reporting tool so that bugs for the
|
||||
contents of both repositories are mixed together and use the same
|
||||
version numbers for all releases (e.g., one launchpad project), they
|
||||
are both part of the same deliverable.
|
||||
|
||||
Within this repository, each deliverable is represented by a separate
|
||||
file within the release series directory or the _independent
|
||||
directory. The data that needs to go into each file is described in
|
||||
detail below. All automated manipulation of the deliverable is managed
|
||||
through the data file, which is reviewed by the core team when the
|
||||
patch is proposed to openstack/releases.
|
||||
|
||||
Requesting a Release
|
||||
====================
|
||||
|
||||
The PTL or release liaison for a project may request a release from
|
||||
master by submitting a patch to this repository, appending 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, appending 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.
|
||||
|
||||
* Always add the new release to the end of the list being edited. The
|
||||
version numbers will be reordered for display.
|
||||
|
||||
* Always pick new version numbers for new releases. We do not update
|
||||
the contents of previously tagged releases, because that confuses
|
||||
users who have already downloaded those packages.
|
||||
|
||||
* 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.
|
||||
|
||||
* Do not increment version numbers artificially to maintain
|
||||
consistent versions between deliverables. We expect versions of
|
||||
compatible deliverables to drift apart over time, and made the
|
||||
decision to embrace this by using other tools to document for users
|
||||
which combinations of packages go together.
|
||||
|
||||
http://lists.openstack.org/pipermail/openstack-dev/2015-June/065992.html
|
||||
|
||||
If two build artifacts always need to have the same version number,
|
||||
that implies strongly that they are part of the same deliverable
|
||||
and should not be released separately.
|
||||
|
||||
* Start version numbers with 0.1.0 for unstable early editions and
|
||||
prototypes. Switch to 1.0.0 for the first production-ready
|
||||
release. Do not release the first version of a deliverable with a
|
||||
number that matches the version used by other existing related
|
||||
deliverables. This confuses consumers about the maturity of the new
|
||||
deliverable and about where they should find "older" versions with
|
||||
lower numbers, which do not exist.
|
||||
|
||||
* 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.
|
||||
|
||||
* Do not use the "Depends-On" feature of zuul to make a release
|
||||
request depend on merging another patch in your project. The
|
||||
dependency management does not work properly in the release check
|
||||
jobs, and the validator requires that the patch listed in your
|
||||
deliverable file actually be merged into a proper branch.
|
||||
|
||||
* Do not submit multiple dependent patches for multiple
|
||||
releases. Having a patch series with multiple releases means the
|
||||
release team cannot properly prioritize processing them. During
|
||||
milestone weeks, preference is given to milestone
|
||||
releases. Releases from stable branches, independent projects, and
|
||||
other types of releases are processed later. If your milestone
|
||||
release request depends on a request that is deprioritized, you may
|
||||
miss the deadline.
|
||||
|
||||
* RC1 tags and stable branches should be submitted together for
|
||||
projects using the cycle-with-milestone release model.
|
||||
|
||||
Using new-release command
|
||||
=========================
|
||||
|
||||
The releases repository contains several tools to make working with
|
||||
the data files easier. The new-release command, for example,
|
||||
calculates new version numbers based on the semantic versioning
|
||||
information given on the command line and determines the SHA of the
|
||||
HEAD of the appropriate branch.
|
||||
|
||||
Use the ``venv`` tox environment to run the tool, like this:
|
||||
|
||||
::
|
||||
|
||||
$ tox -e venv -- new-release SERIES DELIVERABLE TYPE
|
||||
|
||||
The SERIES value should be the release series, such as "pike".
|
||||
|
||||
The DELIVERABLE value should be the deliverable name, such as
|
||||
"oslo.config" or "cinder".
|
||||
|
||||
The TYPE value should be one of:
|
||||
|
||||
bugfix -- For a release containing only bug fixes.
|
||||
|
||||
feature -- For a release with a new feature, a new dependency, or a
|
||||
change to the minimum allowed version of a dependency.
|
||||
|
||||
major -- For a release with a backwards-incompatible change.
|
||||
|
||||
milestone -- For a date-based milestone tag.
|
||||
|
||||
rc -- For a release candidate.
|
||||
|
||||
new-series automatically includes a stable branch for the first
|
||||
release candidate.
|
||||
|
||||
If the most recent release of cinder during the pike series is
|
||||
11.0.0.0b3 then running:
|
||||
|
||||
::
|
||||
|
||||
$ tox -e venv -- new-release pike cinder rc
|
||||
|
||||
detects that this is the first release candidate and updates the file
|
||||
deliverables/pike/cinder.yaml with the new release and a new stable
|
||||
branch.
|
||||
|
||||
If a deliverable includes multiple git repositories, all of the
|
||||
repositories are included in the new release unless their HEAD version
|
||||
matches the most recent release from that repository. To re-tag in
|
||||
those cases, use the --force option.
|
||||
|
||||
Use the --stable-branch option to also create a stable branch for the
|
||||
new release. Projects following the cycle-with-milestones release
|
||||
model automatically receive a new stable branch on their first release
|
||||
candidate.
|
||||
|
||||
Requesting a Branch
|
||||
===================
|
||||
|
||||
The PTL or release liaison for a project may request a new branch by
|
||||
submitting a patch to this repository, adding the necessary branch
|
||||
metadata to the file describing the deliverable to be released. The
|
||||
release team will review the request and provide feedback about the
|
||||
branch point and possibly the name.
|
||||
|
||||
Prepare the branch request by submitting a patch to this repository.
|
||||
|
||||
* RC1 tags and stable branches should be submitted together for
|
||||
projects using the cycle-with-milestone release model.
|
||||
|
||||
* Always add the new branch to the end of the list in the file being
|
||||
edited.
|
||||
|
||||
* Branches should use one of the standard prefixes:
|
||||
|
||||
stable/ -- for stable series
|
||||
|
||||
feature/ -- for temporary feature branches
|
||||
|
||||
driverfixes/ -- for long-term driver maintenance, beyond the end of
|
||||
the stable branch
|
||||
|
||||
* stable/ and driverfixes/ branch names must match a valid series
|
||||
name.
|
||||
|
||||
* If you are not the release liaison or PTL, have the PTL of the
|
||||
project acknowledge the request with a +1.
|
||||
|
||||
* Do not use the "Depends-On" feature of zuul to make a branch
|
||||
request depend on merging another patch in your project. The
|
||||
dependency management does not work properly in the release check
|
||||
jobs, and the validator requires that the patch listed in your
|
||||
deliverable file actually be merged into a proper branch.
|
||||
|
||||
Release Approval
|
||||
================
|
||||
|
||||
Releases will only be denied during freeze weeks, 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
|
||||
=================
|
||||
|
||||
Deliverable repositories for projects using cycle_with_intermediary
|
||||
or cycle_with_milestones should be placed in their respective releases
|
||||
within the deliverables directory. Deliverable repositories for
|
||||
projects using the independent release model should be placed in the
|
||||
``deliverables/_independent`` directory.
|
||||
|
||||
For a deliverable set of projects, we use one YAML file per release
|
||||
series to hold all of the metadata for all releases and branches of
|
||||
that deliverable. For each deliverable, we need to track:
|
||||
|
||||
* the launchpad project name (such as ``oslo.config``) or storyboard
|
||||
project id (such as ``760``)
|
||||
* the series (Kilo, Liberty, etc.)
|
||||
* the release model being used
|
||||
* for each repository
|
||||
|
||||
* the name (such as ``openstack/oslo.config``)
|
||||
* the hash of the commit to be tagged
|
||||
* the version number to use
|
||||
|
||||
* cycle highlights that will be published to
|
||||
``releases.openstack.org/$SERIES/highlights.html`` (optional, and for
|
||||
cycle-with-intermediary, cycle-with-milestones, and cycle-trailing projects
|
||||
only)
|
||||
* the starting points of all branches
|
||||
|
||||
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:
|
||||
|
||||
``team``
|
||||
The name of the team that owns the deliverable, as listed in the
|
||||
governance repository data files.
|
||||
|
||||
``launchpad``
|
||||
The slug name of the launchpad project, suitable for use in URLs.
|
||||
(Not needed for projects using storyboard.)
|
||||
|
||||
``storyboard``
|
||||
The ID of the storyboard project, suitable for use in URLs and API
|
||||
calls. (Not needed for projects using launchpad.)
|
||||
|
||||
``release-notes``
|
||||
The URL or URLs to the published release notes for the deliverable
|
||||
for the series.
|
||||
|
||||
Deliverables contained a single repository should simply include the
|
||||
URL to the notes for that repository. Deliverables made up of
|
||||
multiple repositories should use a hash to map each repository name
|
||||
to its notes URL.
|
||||
|
||||
``include-pypi-link``
|
||||
Either ``yes`` or ``no``, indicating whether the release
|
||||
announcement should include the link to the package on
|
||||
PyPI. Defaults to ``no``.
|
||||
|
||||
``release-model``
|
||||
Identify the release model used by the deliverable. See
|
||||
the reference section of the documentation for descriptions
|
||||
of the valid models.
|
||||
|
||||
``type``
|
||||
Categorize the deliverable based on what it does. See the reference
|
||||
section of the documentation for descriptions of the valid
|
||||
deliverable types.
|
||||
|
||||
``artifact-link-mode``
|
||||
Describe how to link to artifacts produced by the project. The
|
||||
default is ``tarball``. Valid values are:
|
||||
|
||||
tarball
|
||||
Automatically generates links to version-specific files on
|
||||
tarballs.openstack.org.
|
||||
|
||||
none
|
||||
Do not link to anything, just show the version number.
|
||||
|
||||
``repository-settings``
|
||||
Mapping of special settings to control the behavior for each repository,
|
||||
keyed by the repository name.
|
||||
|
||||
``flags``
|
||||
A list of flags attached to the repository.
|
||||
|
||||
``no-artifact-build-job``
|
||||
This repository has no job for building an artifact, but should
|
||||
be tagged anyway.
|
||||
|
||||
``retired``
|
||||
This repository is no longer used, but was present in old
|
||||
versions of a deliverable.
|
||||
|
||||
``pypi-name``
|
||||
An optional name for the deliverable on pypi.python.org. This
|
||||
value is only needed if the name on PyPI does not match the
|
||||
canonicalized output of ``python setup.py --name``, such as if it
|
||||
uses capitalized letters ("DragonFlow" instead of "dragonflow").
|
||||
|
||||
``release-type``
|
||||
This (optional) key sets the level of validation for the versions numbers.
|
||||
|
||||
``python-service``
|
||||
Default: Enforces 3 digit semver version numbers in releases and allows
|
||||
for common alpha, beta and dev releases. This should be appropriate for
|
||||
most OpenStack component release requirements.
|
||||
|
||||
``python-pypi``
|
||||
Like ``python-service`` but requires the jobs to publish the component
|
||||
to the Python Package Index (PyPI).
|
||||
|
||||
``xstatic``
|
||||
Allows a more flexible versioning in line with xstatic package guidelines
|
||||
and requirements.
|
||||
|
||||
``fuel``
|
||||
The Fuel project manages its own packages.
|
||||
|
||||
``puppet``
|
||||
All puppet modules should use this. If no release-type is
|
||||
specified and the validation job can determine that a module is a
|
||||
puppet module, it assumes a release-type of ``puppet``.
|
||||
|
||||
``nodejs``
|
||||
All nodejs modules should use this. If no release-type is
|
||||
specified and the validation job can determine that a module is a
|
||||
nodejs module, it assumes a release-type of ``nodejs``.
|
||||
|
||||
``neutron``
|
||||
For projects using the PyPI publishing variant that installs
|
||||
neutron in order to build the package. Typically used by neutron
|
||||
plugins.
|
||||
|
||||
``horizon``
|
||||
For projects using the PyPI publishing variant that installs
|
||||
horizon in order to build the package. Typically used by horizon
|
||||
plugins.
|
||||
|
||||
``releases``
|
||||
A list of the releases for the deliverable.
|
||||
|
||||
``stable-branch-type``
|
||||
This (optional) key sets the validation for the location associated
|
||||
with each stable branch.
|
||||
|
||||
``std``
|
||||
Default: Requires stable branches to be created from tagged
|
||||
releases. This is the correct branch type for most projects.
|
||||
|
||||
The location must be either an existing version tag or the most
|
||||
recently added version number under the releases list (allowing a
|
||||
tag and branch to be submitted together). All repositories
|
||||
associated with the version (as identified by the deliverable
|
||||
file) will be branched from that version using the name given.
|
||||
|
||||
``tagless``
|
||||
This mode requires stable branch locations to be a mapping between
|
||||
repository name and an existing commit, specified by the
|
||||
hash. This mode should only be used for projects that do not tag
|
||||
releases, such as devstack and grenade.
|
||||
|
||||
``upstream``
|
||||
Stable branch names track upstream release names, rather than
|
||||
OpenStack series names.
|
||||
|
||||
``cycle-highlights``
|
||||
A list of plain-text bullet points describing some of the top new
|
||||
features or changes you would like to point out for this release
|
||||
cycle. Minimal RST markup is supported. These highlights are
|
||||
compiled per team and published to
|
||||
``releases.openstack.org/$SERIES/highlights.html``.
|
||||
|
||||
``branches``
|
||||
A list of the branches 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.)
|
||||
|
||||
``flags``
|
||||
A list of flags attached to the release.
|
||||
|
||||
``forced``
|
||||
This release was applied by the release team, and not the project
|
||||
team.
|
||||
|
||||
Each entry in the ``projects`` list 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.
|
||||
|
||||
``tarball-base``
|
||||
An optional name for the base of the tarball created by the
|
||||
release. If no value is provided, it defaults to the repo base name.
|
||||
|
||||
Each entry in the ``branches`` list is a mapping with keys:
|
||||
|
||||
``name``
|
||||
The name of the branch.
|
||||
|
||||
``location``
|
||||
The location value depends on the name.
|
||||
|
||||
If a branch name starts with stable/ then the location value depends
|
||||
on the ``stable-branch-type`` setting.
|
||||
|
||||
If a branch name starts with feature/ then the location must be a
|
||||
mapping between the target repository name and the SHA of a commit
|
||||
already in the target repository.
|
||||
|
||||
If a branch name starts with driverfixes/ then the location must be
|
||||
a mapping between the target repository name and the SHA of a commit
|
||||
already in the target repository on the associated stable branch.
|
||||
|
||||
|
||||
Examples
|
||||
========
|
||||
|
||||
For example, one version of
|
||||
``deliverables/liberty/oslo.config.yaml`` might contain::
|
||||
|
||||
---
|
||||
launchpad: oslo.config
|
||||
branches:
|
||||
- name: feature/random-feature-work
|
||||
location:
|
||||
openstack/oslo.config: 02a86d2eefeda5144ea8c39657aed24b8b0c9a39
|
||||
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
|
||||
branches:
|
||||
- name: feature/random-feature-work
|
||||
location:
|
||||
openstack/oslo.config: 02a86d2eefeda5144ea8c39657aed24b8b0c9a39
|
||||
- name: stable/newton
|
||||
location: 1.12.1
|
||||
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.
|
||||
|
||||
A driverfixes branch might be added to a project in a similar
|
||||
way. This example shows the branch created in cinder for the newton
|
||||
series. The branch was created from the HEAD of the stable/newton
|
||||
branch at the time.
|
||||
|
||||
::
|
||||
|
||||
---
|
||||
launchpad: cinder
|
||||
team: cinder
|
||||
type: service
|
||||
release-model: cycle-with-milestones
|
||||
release-notes: https://docs.openstack.org/releasenotes/cinder/newton.html
|
||||
branches:
|
||||
- name: stable/newton
|
||||
location: 9.0.0.0rc1
|
||||
- name: driverfixes/newton
|
||||
location:
|
||||
openstack/cinder: 08bfc7d817f313451e619b535299121b686d7bd8
|
||||
releases:
|
||||
# ...
|
||||
- version: 9.0.0.0rc1
|
||||
projects:
|
||||
- repo: openstack/cinder
|
||||
hash: 0ba267fbc1836722735102994b466ecd7803b10a
|
||||
- version: 9.0.0.0rc2
|
||||
projects:
|
||||
- repo: openstack/cinder
|
||||
hash: ab9518112137f3141739e873b19cdc0085963bc7
|
||||
# ...
|
||||
- version: 9.1.4
|
||||
projects:
|
||||
- repo: openstack/cinder
|
||||
hash: 908def6bb993798146cccc1621a9cee18950629d
|
||||
|
||||
For deliverables with multiple repositories, the list of projects
|
||||
would contain all of them. For example, the Neutron deliverable might
|
||||
be described by ``deliverables/mitaka/neutron.yaml`` containing:
|
||||
|
||||
::
|
||||
|
||||
---
|
||||
launchpad: neutron
|
||||
release-notes:
|
||||
openstack/neutron: https://docs.openstack.org/releasenotes/neutron/mitaka.html
|
||||
openstack/neutron-lbaas: https://docs.openstack.org/releasenotes/neutron-lbaas/mitaka.html
|
||||
openstack/neutron-fwaas: https://docs.openstack.org/releasenotes/neutron-fwaas/mitaka.html
|
||||
openstack/neutron-vpnaas: https://docs.openstack.org/releasenotes/neutron-vpnaas/mitaka.html
|
||||
releases:
|
||||
- version: 8.0.0
|
||||
projects:
|
||||
- repo: openstack/neutron
|
||||
hash: 3213eb124e40b130e174ac3a91067e2b196788dd
|
||||
- repo: openstack/neutron-fwaas
|
||||
hash: ab5622891e2b1a7631f97471f55ffb9b5235e5ee
|
||||
- repo: openstack/neutron-lbaas
|
||||
hash: 19b18f05037dae4bbbada848aae6421da18ab490
|
||||
- repo: openstack/neutron-vpnaas
|
||||
hash: a1b12601a64a2359b2224fd4406c5db008484700
|
||||
|
||||
To allow tagging for repositories without build artifacts, set the
|
||||
``no-artifact-build-job`` flag.
|
||||
|
||||
::
|
||||
|
||||
---
|
||||
launchpad: astara
|
||||
repository-settings:
|
||||
openstack/astara-appliance:
|
||||
flags:
|
||||
- no-artifact-build-job
|
||||
releases:
|
||||
- version: 9.0.0.0b1
|
||||
projects:
|
||||
- repo: openstack/astara-appliance
|
||||
hash: c21a64ea7b3b0fbdab8592afecdd31d9b8e64a6a
|
||||
|
||||
Helpers
|
||||
=======
|
||||
|
||||
In order to help build out these files there are various command line
|
||||
based tools that come with this repository. To install these it is as
|
||||
easy as ``pip install .`` in this repository directory.
|
||||
|
||||
* ``new-release`` takes arguments to describe a new release and
|
||||
updates the deliverable file, automatically calculating the version
|
||||
number
|
||||
* ``edit-deliverable`` takes arguments to update the contents of a
|
||||
single deliverable file
|
||||
* ``list-changes`` that lists the changes in a given release file.
|
||||
* ``interactive-release`` that goes through a *wizard* style set of
|
||||
questions to produce a new or updated release of a given project or
|
||||
set of projects.
|
||||
* ``missing-releases`` scans deliverable files and verifies that all
|
||||
of the releases that should have been tagged by hand have been
|
||||
* ``init-series`` initializes a new deliverable directory with stub
|
||||
files based on the previous release.
|
||||
|
||||
tools/aclmanager.py
|
||||
-------------------
|
||||
|
||||
A script to handle pre-release/post-release ACLs on stable/$SERIES
|
||||
branches.
|
||||
|
||||
The 'acls' action helps to produce a patch over
|
||||
openstack-infra/project-config that inserts a specific ACL for
|
||||
stable/$SERIES.
|
||||
|
||||
The 'groups' action helps to adjust the membership of
|
||||
$PROJ-release-branch Gerrit group, based on which stage the release
|
||||
branch is at. At pre-release we remove $PROJ-stable-maint, and add the
|
||||
$PROJ-release and Release Managers group (pre_release subaction). At
|
||||
post-release, we remove $PROJ-release and Release Managers, and add
|
||||
$PROJ-stable-maint (post_release subaction).
|
||||
|
||||
Examples:
|
||||
|
||||
To create the ACL patch for stable/newton:
|
||||
|
||||
::
|
||||
|
||||
tox -e aclmanager -- --series newton acls ~/branches/openstack-infra/project-config
|
||||
|
||||
To set the pre-release group membership:
|
||||
|
||||
::
|
||||
|
||||
tox -e aclmanager -- groups pre_release ttx
|
||||
|
||||
propose-final-releases
|
||||
----------------------
|
||||
|
||||
Command to edit the deliverable files in a releases repository to
|
||||
propose final releases. The command modifies files in an existing copy
|
||||
of the repository and does not invoke git at all, so you need to
|
||||
create a branch before running it then review the output, commit the
|
||||
changes, and push the patch to gerrit.
|
||||
|
||||
::
|
||||
|
||||
tox -e venv -- propose-final-releases newton ocata
|
||||
|
||||
propose-library-branches
|
||||
------------------------
|
||||
|
||||
Command to edit the deliverable files in a releases repository to
|
||||
propose stable branches for libraries. The command modifies files in
|
||||
an existing copy of the repository and does not invoke git at all, so
|
||||
you need to create a branch before running it then review the output,
|
||||
commit the changes, and push the patch to gerrit.
|
||||
|
||||
::
|
||||
|
||||
tox -e venv -- propose-library-branches
|
||||
tox -e venv -- propose-library-branches pike
|
||||
|
||||
tools/list_unreleased_changes.sh
|
||||
--------------------------------
|
||||
|
||||
Given a branch and one or more repositories, produce a list of the
|
||||
changes in those repositories since their last tag on that
|
||||
branch. This is useful for deciding if a project needs to prepare a
|
||||
release, and for predicting what the next release version should be by
|
||||
looking at the commit logs.
|
||||
|
||||
::
|
||||
|
||||
./tools/list_unreleased_changes.sh master openstack/oslo.config
|
||||
|
||||
Print the list of changes in ``openstack/oslo.config`` along the
|
||||
master branch.
|
||||
|
||||
::
|
||||
|
||||
./tools/list_unreleased_changes.sh stable/kilo $(list-deliverables --repos --team Oslo)
|
||||
|
||||
Print the list of changes in the ``stable/kilo`` branch of all Oslo
|
||||
libraries.
|
||||
|
||||
tools/list_library_unreleased_changes.sh
|
||||
----------------------------------------
|
||||
|
||||
Runs list_unreleased_changes.sh for all libraries managed by any
|
||||
project.
|
||||
|
||||
list_stable_unreleased_changes.sh
|
||||
---------------------------------
|
||||
|
||||
Runs list_unreleased_changes.sh with the given branch for all
|
||||
repositories tagged with ``stable:follows-policy``.
|
||||
|
||||
|
||||
::
|
||||
|
||||
./list_stable_unreleased_changes.sh stable/liberty
|
||||
|
||||
|
||||
is equivalent to:
|
||||
|
||||
::
|
||||
|
||||
./list_unreleased_changes.sh stable/liberty $(list-deliverables --repos --series liberty)
|
||||
Refer to `the reference documentation
|
||||
<https://releases.openstack.org/reference/>`_ for more details
|
||||
|
||||
721
doc/source/reference/using.rst
Normal file
721
doc/source/reference/using.rst
Normal file
@ -0,0 +1,721 @@
|
||||
=======================
|
||||
Using This Repository
|
||||
=======================
|
||||
|
||||
This repository is for tracking release requests for OpenStack
|
||||
projects. The releases are managed using groups of "deliverables",
|
||||
made up of individual project repositories sharing a Launchpad group
|
||||
and a version number history. Many deliverables will only have one
|
||||
constituent project.
|
||||
|
||||
Defining a Deliverable
|
||||
======================
|
||||
|
||||
A "deliverable" is a unit of distribution of a useful project. It may
|
||||
be a single library or several server components that are packaged
|
||||
separately but released and used together. Rather than base the
|
||||
definition on technical terms such as packaging, we use the social
|
||||
organization of the project to identify deliverables. If the contents
|
||||
of two repositories share a bug reporting tool so that bugs for the
|
||||
contents of both repositories are mixed together and use the same
|
||||
version numbers for all releases (e.g., one launchpad project), they
|
||||
are both part of the same deliverable.
|
||||
|
||||
Within this repository, each deliverable is represented by a separate
|
||||
file within the release series directory or the _independent
|
||||
directory. The data that needs to go into each file is described in
|
||||
detail below. All automated manipulation of the deliverable is managed
|
||||
through the data file, which is reviewed by the core team when the
|
||||
patch is proposed to openstack/releases.
|
||||
|
||||
Requesting a Release
|
||||
====================
|
||||
|
||||
The PTL or release liaison for a project may request a release from
|
||||
master by submitting a patch to this repository, appending 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, appending 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.
|
||||
|
||||
* Always add the new release to the end of the list being edited. The
|
||||
version numbers will be reordered for display.
|
||||
|
||||
* Always pick new version numbers for new releases. We do not update
|
||||
the contents of previously tagged releases, because that confuses
|
||||
users who have already downloaded those packages.
|
||||
|
||||
* 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.
|
||||
|
||||
* Do not increment version numbers artificially to maintain
|
||||
consistent versions between deliverables. We expect versions of
|
||||
compatible deliverables to drift apart over time, and made the
|
||||
decision to embrace this by using other tools to document for users
|
||||
which combinations of packages go together.
|
||||
|
||||
http://lists.openstack.org/pipermail/openstack-dev/2015-June/065992.html
|
||||
|
||||
If two build artifacts always need to have the same version number,
|
||||
that implies strongly that they are part of the same deliverable
|
||||
and should not be released separately.
|
||||
|
||||
* Start version numbers with 0.1.0 for unstable early editions and
|
||||
prototypes. Switch to 1.0.0 for the first production-ready
|
||||
release. Do not release the first version of a deliverable with a
|
||||
number that matches the version used by other existing related
|
||||
deliverables. This confuses consumers about the maturity of the new
|
||||
deliverable and about where they should find "older" versions with
|
||||
lower numbers, which do not exist.
|
||||
|
||||
* 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.
|
||||
|
||||
* Do not use the "Depends-On" feature of zuul to make a release
|
||||
request depend on merging another patch in your project. The
|
||||
dependency management does not work properly in the release check
|
||||
jobs, and the validator requires that the patch listed in your
|
||||
deliverable file actually be merged into a proper branch.
|
||||
|
||||
* Do not submit multiple dependent patches for multiple
|
||||
releases. Having a patch series with multiple releases means the
|
||||
release team cannot properly prioritize processing them. During
|
||||
milestone weeks, preference is given to milestone
|
||||
releases. Releases from stable branches, independent projects, and
|
||||
other types of releases are processed later. If your milestone
|
||||
release request depends on a request that is deprioritized, you may
|
||||
miss the deadline.
|
||||
|
||||
* RC1 tags and stable branches should be submitted together for
|
||||
projects using the cycle-with-milestone release model.
|
||||
|
||||
Using new-release command
|
||||
=========================
|
||||
|
||||
The releases repository contains several tools to make working with
|
||||
the data files easier. The new-release command, for example,
|
||||
calculates new version numbers based on the semantic versioning
|
||||
information given on the command line and determines the SHA of the
|
||||
HEAD of the appropriate branch.
|
||||
|
||||
Use the ``venv`` tox environment to run the tool, like this:
|
||||
|
||||
::
|
||||
|
||||
$ tox -e venv -- new-release SERIES DELIVERABLE TYPE
|
||||
|
||||
The SERIES value should be the release series, such as "pike".
|
||||
|
||||
The DELIVERABLE value should be the deliverable name, such as
|
||||
"oslo.config" or "cinder".
|
||||
|
||||
The TYPE value should be one of:
|
||||
|
||||
``bugfix`` -- For a release containing only bug fixes.
|
||||
|
||||
``feature`` -- For a release with a new feature, a new dependency, or
|
||||
a change to the minimum allowed version of a dependency.
|
||||
|
||||
``major`` -- For a release with a backwards-incompatible change.
|
||||
|
||||
``milestone`` -- For a date-based milestone tag.
|
||||
|
||||
``rc`` -- For a release candidate.
|
||||
|
||||
new-series automatically includes a stable branch for the first
|
||||
release candidate.
|
||||
|
||||
If the most recent release of cinder during the pike series is
|
||||
11.0.0.0b3 then running:
|
||||
|
||||
::
|
||||
|
||||
$ tox -e venv -- new-release pike cinder rc
|
||||
|
||||
detects that this is the first release candidate and updates the file
|
||||
deliverables/pike/cinder.yaml with the new release and a new stable
|
||||
branch.
|
||||
|
||||
If a deliverable includes multiple git repositories, all of the
|
||||
repositories are included in the new release unless their HEAD version
|
||||
matches the most recent release from that repository. To re-tag in
|
||||
those cases, use the --force option.
|
||||
|
||||
Use the --stable-branch option to also create a stable branch for the
|
||||
new release. Projects following the cycle-with-milestones release
|
||||
model automatically receive a new stable branch on their first release
|
||||
candidate.
|
||||
|
||||
Requesting a Branch
|
||||
===================
|
||||
|
||||
The PTL or release liaison for a project may request a new branch by
|
||||
submitting a patch to this repository, adding the necessary branch
|
||||
metadata to the file describing the deliverable to be released. The
|
||||
release team will review the request and provide feedback about the
|
||||
branch point and possibly the name.
|
||||
|
||||
Prepare the branch request by submitting a patch to this repository.
|
||||
|
||||
* RC1 tags and stable branches should be submitted together for
|
||||
projects using the cycle-with-milestone release model.
|
||||
|
||||
* Always add the new branch to the end of the list in the file being
|
||||
edited.
|
||||
|
||||
* Branches should use one of the standard prefixes:
|
||||
|
||||
``stable/`` -- for stable series
|
||||
|
||||
``feature/`` -- for temporary feature branches
|
||||
|
||||
``driverfixes/`` -- for long-term driver maintenance, beyond the end of
|
||||
the stable branch
|
||||
|
||||
* ``stable/`` and ``driverfixes/`` branch names must match a valid series
|
||||
name.
|
||||
|
||||
* If you are not the release liaison or PTL, have the PTL of the
|
||||
project acknowledge the request with a +1.
|
||||
|
||||
* Do not use the "Depends-On" feature of zuul to make a branch
|
||||
request depend on merging another patch in your project. The
|
||||
dependency management does not work properly in the release check
|
||||
jobs, and the validator requires that the patch listed in your
|
||||
deliverable file actually be merged into a proper branch.
|
||||
|
||||
Release Approval
|
||||
================
|
||||
|
||||
Releases will only be denied during freeze weeks, 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
|
||||
=================
|
||||
|
||||
Deliverable repositories for projects using cycle_with_intermediary
|
||||
or cycle_with_milestones should be placed in their respective releases
|
||||
within the deliverables directory. Deliverable repositories for
|
||||
projects using the independent release model should be placed in the
|
||||
``deliverables/_independent`` directory.
|
||||
|
||||
For a deliverable set of projects, we use one YAML file per release
|
||||
series to hold all of the metadata for all releases and branches of
|
||||
that deliverable. For each deliverable, we need to track:
|
||||
|
||||
* the launchpad project name (such as ``oslo.config``) or storyboard
|
||||
project id (such as ``760``)
|
||||
* the series (Kilo, Liberty, etc.)
|
||||
* the release model being used
|
||||
* for each repository
|
||||
|
||||
* the name (such as ``openstack/oslo.config``)
|
||||
* the hash of the commit to be tagged
|
||||
* the version number to use
|
||||
|
||||
* cycle highlights that will be published to
|
||||
``releases.openstack.org/$SERIES/highlights.html`` (optional, and for
|
||||
cycle-with-intermediary, cycle-with-milestones, and cycle-trailing projects
|
||||
only)
|
||||
* the starting points of all branches
|
||||
|
||||
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:
|
||||
|
||||
``team``
|
||||
The name of the team that owns the deliverable, as listed in the
|
||||
governance repository data files.
|
||||
|
||||
``launchpad``
|
||||
The slug name of the launchpad project, suitable for use in URLs.
|
||||
(Not needed for projects using storyboard.)
|
||||
|
||||
``storyboard``
|
||||
The ID of the storyboard project, suitable for use in URLs and API
|
||||
calls. (Not needed for projects using launchpad.)
|
||||
|
||||
``release-notes``
|
||||
The URL or URLs to the published release notes for the deliverable
|
||||
for the series.
|
||||
|
||||
Deliverables contained a single repository should simply include the
|
||||
URL to the notes for that repository. Deliverables made up of
|
||||
multiple repositories should use a hash to map each repository name
|
||||
to its notes URL.
|
||||
|
||||
``include-pypi-link``
|
||||
Either ``yes`` or ``no``, indicating whether the release
|
||||
announcement should include the link to the package on
|
||||
PyPI. Defaults to ``no``.
|
||||
|
||||
``release-model``
|
||||
Identify the release model used by the deliverable. See
|
||||
the reference section of the documentation for descriptions
|
||||
of the valid models.
|
||||
|
||||
``type``
|
||||
Categorize the deliverable based on what it does. See the reference
|
||||
section of the documentation for descriptions of the valid
|
||||
deliverable types.
|
||||
|
||||
``artifact-link-mode``
|
||||
Describe how to link to artifacts produced by the project. The
|
||||
default is ``tarball``. Valid values are:
|
||||
|
||||
``tarball``
|
||||
Automatically generates links to version-specific files on
|
||||
tarballs.openstack.org.
|
||||
|
||||
``none``
|
||||
Do not link to anything, just show the version number.
|
||||
|
||||
``repository-settings``
|
||||
Mapping of special settings to control the behavior for each repository,
|
||||
keyed by the repository name.
|
||||
|
||||
``flags``
|
||||
A list of flags attached to the repository.
|
||||
|
||||
``no-artifact-build-job``
|
||||
This repository has no job for building an artifact, but should
|
||||
be tagged anyway.
|
||||
|
||||
``retired``
|
||||
This repository is no longer used, but was present in old
|
||||
versions of a deliverable.
|
||||
|
||||
``pypi-name``
|
||||
An optional name for the deliverable on pypi.python.org. This
|
||||
value is only needed if the name on PyPI does not match the
|
||||
canonicalized output of ``python setup.py --name``, such as if it
|
||||
uses capitalized letters ("DragonFlow" instead of "dragonflow").
|
||||
|
||||
``release-type``
|
||||
This (optional) key sets the level of validation for the versions numbers.
|
||||
|
||||
``python-service``
|
||||
Default: Enforces 3 digit semver version numbers in releases and allows
|
||||
for common alpha, beta and dev releases. This should be appropriate for
|
||||
most OpenStack component release requirements.
|
||||
|
||||
``python-pypi``
|
||||
Like ``python-service`` but requires the jobs to publish the component
|
||||
to the Python Package Index (PyPI).
|
||||
|
||||
``xstatic``
|
||||
Allows a more flexible versioning in line with xstatic package guidelines
|
||||
and requirements.
|
||||
|
||||
``fuel``
|
||||
The Fuel project manages its own packages.
|
||||
|
||||
``puppet``
|
||||
All puppet modules should use this. If no release-type is
|
||||
specified and the validation job can determine that a module is a
|
||||
puppet module, it assumes a release-type of ``puppet``.
|
||||
|
||||
``nodejs``
|
||||
All nodejs modules should use this. If no release-type is
|
||||
specified and the validation job can determine that a module is a
|
||||
nodejs module, it assumes a release-type of ``nodejs``.
|
||||
|
||||
``neutron``
|
||||
For projects using the PyPI publishing variant that installs
|
||||
neutron in order to build the package. Typically used by neutron
|
||||
plugins.
|
||||
|
||||
``horizon``
|
||||
For projects using the PyPI publishing variant that installs
|
||||
horizon in order to build the package. Typically used by horizon
|
||||
plugins.
|
||||
|
||||
``releases``
|
||||
A list of the releases for the deliverable.
|
||||
|
||||
``stable-branch-type``
|
||||
This (optional) key sets the validation for the location associated
|
||||
with each stable branch.
|
||||
|
||||
``std``
|
||||
Default: Requires stable branches to be created from tagged
|
||||
releases. This is the correct branch type for most projects.
|
||||
|
||||
The location must be either an existing version tag or the most
|
||||
recently added version number under the releases list (allowing a
|
||||
tag and branch to be submitted together). All repositories
|
||||
associated with the version (as identified by the deliverable
|
||||
file) will be branched from that version using the name given.
|
||||
|
||||
``tagless``
|
||||
This mode requires stable branch locations to be a mapping between
|
||||
repository name and an existing commit, specified by the
|
||||
hash. This mode should only be used for projects that do not tag
|
||||
releases, such as devstack and grenade.
|
||||
|
||||
``upstream``
|
||||
Stable branch names track upstream release names, rather than
|
||||
OpenStack series names.
|
||||
|
||||
``cycle-highlights``
|
||||
A list of plain-text bullet points describing some of the top new
|
||||
features or changes you would like to point out for this release
|
||||
cycle. Minimal RST markup is supported. These highlights are
|
||||
compiled per team and published to
|
||||
``releases.openstack.org/$SERIES/highlights.html``.
|
||||
|
||||
``branches``
|
||||
A list of the branches 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.)
|
||||
|
||||
``flags``
|
||||
A list of flags attached to the release.
|
||||
|
||||
``forced``
|
||||
This release was applied by the release team, and not the project
|
||||
team.
|
||||
|
||||
Each entry in the ``projects`` list 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.
|
||||
|
||||
``tarball-base``
|
||||
An optional name for the base of the tarball created by the
|
||||
release. If no value is provided, it defaults to the repo base name.
|
||||
|
||||
Each entry in the ``branches`` list is a mapping with keys:
|
||||
|
||||
``name``
|
||||
The name of the branch.
|
||||
|
||||
``location``
|
||||
The location value depends on the name.
|
||||
|
||||
If a branch name starts with stable/ then the location value depends
|
||||
on the ``stable-branch-type`` setting.
|
||||
|
||||
If a branch name starts with feature/ then the location must be a
|
||||
mapping between the target repository name and the SHA of a commit
|
||||
already in the target repository.
|
||||
|
||||
If a branch name starts with driverfixes/ then the location must be
|
||||
a mapping between the target repository name and the SHA of a commit
|
||||
already in the target repository on the associated stable branch.
|
||||
|
||||
|
||||
Examples
|
||||
========
|
||||
|
||||
For example, one version of
|
||||
``deliverables/liberty/oslo.config.yaml`` might contain::
|
||||
|
||||
---
|
||||
launchpad: oslo.config
|
||||
branches:
|
||||
- name: feature/random-feature-work
|
||||
location:
|
||||
openstack/oslo.config: 02a86d2eefeda5144ea8c39657aed24b8b0c9a39
|
||||
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
|
||||
branches:
|
||||
- name: feature/random-feature-work
|
||||
location:
|
||||
openstack/oslo.config: 02a86d2eefeda5144ea8c39657aed24b8b0c9a39
|
||||
- name: stable/newton
|
||||
location: 1.12.1
|
||||
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.
|
||||
|
||||
A driverfixes branch might be added to a project in a similar
|
||||
way. This example shows the branch created in cinder for the newton
|
||||
series. The branch was created from the HEAD of the stable/newton
|
||||
branch at the time.
|
||||
|
||||
::
|
||||
|
||||
---
|
||||
launchpad: cinder
|
||||
team: cinder
|
||||
type: service
|
||||
release-model: cycle-with-milestones
|
||||
release-notes: https://docs.openstack.org/releasenotes/cinder/newton.html
|
||||
branches:
|
||||
- name: stable/newton
|
||||
location: 9.0.0.0rc1
|
||||
- name: driverfixes/newton
|
||||
location:
|
||||
openstack/cinder: 08bfc7d817f313451e619b535299121b686d7bd8
|
||||
releases:
|
||||
# ...
|
||||
- version: 9.0.0.0rc1
|
||||
projects:
|
||||
- repo: openstack/cinder
|
||||
hash: 0ba267fbc1836722735102994b466ecd7803b10a
|
||||
- version: 9.0.0.0rc2
|
||||
projects:
|
||||
- repo: openstack/cinder
|
||||
hash: ab9518112137f3141739e873b19cdc0085963bc7
|
||||
# ...
|
||||
- version: 9.1.4
|
||||
projects:
|
||||
- repo: openstack/cinder
|
||||
hash: 908def6bb993798146cccc1621a9cee18950629d
|
||||
|
||||
For deliverables with multiple repositories, the list of projects
|
||||
would contain all of them. For example, the Neutron deliverable might
|
||||
be described by ``deliverables/mitaka/neutron.yaml`` containing:
|
||||
|
||||
::
|
||||
|
||||
---
|
||||
launchpad: neutron
|
||||
release-notes:
|
||||
openstack/neutron: https://docs.openstack.org/releasenotes/neutron/mitaka.html
|
||||
openstack/neutron-lbaas: https://docs.openstack.org/releasenotes/neutron-lbaas/mitaka.html
|
||||
openstack/neutron-fwaas: https://docs.openstack.org/releasenotes/neutron-fwaas/mitaka.html
|
||||
openstack/neutron-vpnaas: https://docs.openstack.org/releasenotes/neutron-vpnaas/mitaka.html
|
||||
releases:
|
||||
- version: 8.0.0
|
||||
projects:
|
||||
- repo: openstack/neutron
|
||||
hash: 3213eb124e40b130e174ac3a91067e2b196788dd
|
||||
- repo: openstack/neutron-fwaas
|
||||
hash: ab5622891e2b1a7631f97471f55ffb9b5235e5ee
|
||||
- repo: openstack/neutron-lbaas
|
||||
hash: 19b18f05037dae4bbbada848aae6421da18ab490
|
||||
- repo: openstack/neutron-vpnaas
|
||||
hash: a1b12601a64a2359b2224fd4406c5db008484700
|
||||
|
||||
To allow tagging for repositories without build artifacts, set the
|
||||
``no-artifact-build-job`` flag.
|
||||
|
||||
::
|
||||
|
||||
---
|
||||
launchpad: astara
|
||||
repository-settings:
|
||||
openstack/astara-appliance:
|
||||
flags:
|
||||
- no-artifact-build-job
|
||||
releases:
|
||||
- version: 9.0.0.0b1
|
||||
projects:
|
||||
- repo: openstack/astara-appliance
|
||||
hash: c21a64ea7b3b0fbdab8592afecdd31d9b8e64a6a
|
||||
|
||||
Helpers
|
||||
=======
|
||||
|
||||
In order to help build out these files there are various command line
|
||||
based tools that come with this repository. To install these it is as
|
||||
easy as ``pip install .`` in this repository directory.
|
||||
|
||||
* ``new-release`` takes arguments to describe a new release and
|
||||
updates the deliverable file, automatically calculating the version
|
||||
number
|
||||
* ``edit-deliverable`` takes arguments to update the contents of a
|
||||
single deliverable file
|
||||
* ``list-changes`` that lists the changes in a given release file.
|
||||
* ``interactive-release`` that goes through a *wizard* style set of
|
||||
questions to produce a new or updated release of a given project or
|
||||
set of projects.
|
||||
* ``missing-releases`` scans deliverable files and verifies that all
|
||||
of the releases that should have been tagged by hand have been
|
||||
* ``init-series`` initializes a new deliverable directory with stub
|
||||
files based on the previous release.
|
||||
|
||||
tools/aclmanager.py
|
||||
-------------------
|
||||
|
||||
A script to handle pre-release/post-release ACLs on stable/$SERIES
|
||||
branches.
|
||||
|
||||
The 'acls' action helps to produce a patch over
|
||||
openstack-infra/project-config that inserts a specific ACL for
|
||||
stable/$SERIES.
|
||||
|
||||
The 'groups' action helps to adjust the membership of
|
||||
$PROJ-release-branch Gerrit group, based on which stage the release
|
||||
branch is at. At pre-release we remove $PROJ-stable-maint, and add the
|
||||
$PROJ-release and Release Managers group (pre_release subaction). At
|
||||
post-release, we remove $PROJ-release and Release Managers, and add
|
||||
$PROJ-stable-maint (post_release subaction).
|
||||
|
||||
Examples:
|
||||
|
||||
To create the ACL patch for stable/newton:
|
||||
|
||||
::
|
||||
|
||||
tox -e aclmanager -- --series newton acls ~/branches/openstack-infra/project-config
|
||||
|
||||
To set the pre-release group membership:
|
||||
|
||||
::
|
||||
|
||||
tox -e aclmanager -- groups pre_release ttx
|
||||
|
||||
propose-final-releases
|
||||
----------------------
|
||||
|
||||
Command to edit the deliverable files in a releases repository to
|
||||
propose final releases. The command modifies files in an existing copy
|
||||
of the repository and does not invoke git at all, so you need to
|
||||
create a branch before running it then review the output, commit the
|
||||
changes, and push the patch to gerrit.
|
||||
|
||||
::
|
||||
|
||||
tox -e venv -- propose-final-releases newton ocata
|
||||
|
||||
propose-library-branches
|
||||
------------------------
|
||||
|
||||
Command to edit the deliverable files in a releases repository to
|
||||
propose stable branches for libraries. The command modifies files in
|
||||
an existing copy of the repository and does not invoke git at all, so
|
||||
you need to create a branch before running it then review the output,
|
||||
commit the changes, and push the patch to gerrit.
|
||||
|
||||
::
|
||||
|
||||
tox -e venv -- propose-library-branches
|
||||
tox -e venv -- propose-library-branches pike
|
||||
|
||||
tools/list_unreleased_changes.sh
|
||||
--------------------------------
|
||||
|
||||
Given a branch and one or more repositories, produce a list of the
|
||||
changes in those repositories since their last tag on that
|
||||
branch. This is useful for deciding if a project needs to prepare a
|
||||
release, and for predicting what the next release version should be by
|
||||
looking at the commit logs.
|
||||
|
||||
::
|
||||
|
||||
./tools/list_unreleased_changes.sh master openstack/oslo.config
|
||||
|
||||
Print the list of changes in ``openstack/oslo.config`` along the
|
||||
master branch.
|
||||
|
||||
::
|
||||
|
||||
./tools/list_unreleased_changes.sh stable/kilo $(list-deliverables --repos --team Oslo)
|
||||
|
||||
Print the list of changes in the ``stable/kilo`` branch of all Oslo
|
||||
libraries.
|
||||
|
||||
tools/list_library_unreleased_changes.sh
|
||||
----------------------------------------
|
||||
|
||||
Runs list_unreleased_changes.sh for all libraries managed by any
|
||||
project.
|
||||
|
||||
list_stable_unreleased_changes.sh
|
||||
---------------------------------
|
||||
|
||||
Runs list_unreleased_changes.sh with the given branch for all
|
||||
repositories tagged with ``stable:follows-policy``.
|
||||
|
||||
|
||||
::
|
||||
|
||||
./list_stable_unreleased_changes.sh stable/liberty
|
||||
|
||||
|
||||
is equivalent to:
|
||||
|
||||
::
|
||||
|
||||
./list_unreleased_changes.sh stable/liberty $(list-deliverables --repos --series liberty)
|
||||
Loading…
Reference in New Issue
Block a user