improve instructions for defining deliverable and picking version numbers
Add detail about how to define a deliverable based on how the project is managed rather than technical criteria. Move the information about assigning version numbers up to the "how to" section instead of the reviewer section to make it more likely that submitters will read it. Change-Id: I480e91ae69f91b2e87ed83fe343dc546948f31f5 Signed-off-by: Doug Hellmann <doug@doughellmann.com>
This commit is contained in:
parent
09d472a660
commit
9456491e2d
73
README.rst
73
README.rst
|
@ -14,6 +14,26 @@ 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
|
||||
====================
|
||||
|
||||
|
@ -42,6 +62,44 @@ repository.
|
|||
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 other related deliverables
|
||||
use. 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.
|
||||
|
||||
|
@ -115,20 +173,7 @@ stable/liberty).
|
|||
|
||||
General notes when reviewing a 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.
|
||||
|
||||
* Check the version number for SemVer, especially for libraries.
|
||||
* Make sure the summary of the patch includes the deliverable name and
|
||||
version number.
|
||||
|
||||
|
|
Loading…
Reference in New Issue