iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Explain the version scheme in PEP 426

This commit is contained in:
Nick Coghlan 2013-02-09 22:40:18 +10:00
parent f6d09596b2
commit 0668bcba55
1 changed files with 414 additions and 103 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

517
pep-0426.txt
View File

@ -29,7 +29,7 @@ third-party packaging of Python Software easier and defines a formal
extension mechanism. It also adds support for optional features of
distributions and allows the description to be placed into a payload
section. Finally, this version addresses several issues with the
previous iteration of the standard version numbering scheme.
previous iteration of the standard version identification scheme.
Metadata files
@ -101,7 +101,7 @@ Example::
Version
-------
A string containing the distribution's version number. See `Version scheme`_
A string containing the distribution's version identifier. See `Version scheme`_
below.
Example::
@ -300,7 +300,7 @@ that it provides ``ExampleORM-somedb-bindings``, allowing other
projects to depend only on having at least one of them installed.
A version declaration may be supplied and must follow the rules described
in `Version scheme`_. The distribution's version number will be implied
in `Version scheme`_. The distribution's version identifier will be implied
if none is specified.
Examples::
@ -446,7 +446,7 @@ The format of a requirement string is a name of an external
dependency, optionally followed by a version declaration within
parentheses.
Because they refer to non-Python software releases, version numbers
Because they refer to non-Python software releases, version identifiers
for this field are **not** required to conform to the format
described in `Version scheme`_: they should correspond to the
version scheme used by the external dependency.
@ -549,31 +549,310 @@ authors should be conservative in the markup they use.
Version scheme
==============
Version numbers must comply with the following scheme::
Version identifiers must comply with the following scheme::
N.N[.N]+[{a|b|c|rc}N][.postN][.devN]
N[.N]+[{a|b|c|rc}N][.postN][.devN]
Version numbers which do not comply with this scheme are an
error. Projects which wish to use non-compliant version numbers may
be heuristically normalized to this scheme and are less likely to sort
correctly.
Version identifiers which do not comply with this scheme are an error.
Projects which wish to use non-compliant version identifiers must restrict
themselves to metadata v1.1 (PEP 314) or earlier, as those specifications
do not constrain the versioning scheme.
Suffixes and ordering
---------------------
Any given version will be a "release", "pre-release", "post-release" or
"developmental release" as defined in the following sections.
The following suffixes are the only ones allowed at the given level of the
version hierarchy and they are ordered as listed.
.. note::
Within a numeric release (``1.0``, ``2.7.3``)::
Some hard to read version identifiers are permitted by this scheme
in order to better accommodate the wide range of versioning practices
across existing public and private Python projects.
Accordingly, some of the versioning practices which are technically
permitted by the PEP are strongly discouraged for new projects. Where
this is the case, the relevant details are noted in the following
sections.
Releases
--------
A release number is a version identifier that consists solely of one or
more non-negative integer values, separated by dots::
N[.N]+
Releases within a project must be numbered in a consistently increasing
fashion. Ordering considers the numeric value of each component
in turn, with "component does not exist" sorted ahead of all numeric
values.
While any number of additional components after the first are permitted
under this scheme, the most common variants are to use two components
("major.minor") or three components ("major.minor.micro").
For example::
0.9
0.9.1
0.9.2
...
0.9.10
0.9.11
1.0
1.0.1
1.1
2.0
2.0.1
A release series is any set of release numbers that start with a common
prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all
part of the ``3.3`` release series.
.. note::
Using both ``X.Y`` and ``X.Y.0`` as distinct release numbers within the
scope of a single release series is strongly discouraged, as it makes the
version ordering ambiguous for human readers. Automated tools should
either treat this case as an error, or else interpret an ``X.Y.0``
release as coming *after* the corresponding ``X.Y`` release.
The recommended practice is to always use release numbers of a consistent
length (that is, always include the trailing ``.0``). An acceptable
alternative is to consistently omit the trailing ``.0``. The example
above shows both styles, always including the ``.0`` at the second
level and consistently omitting it at the third level.
.. note::
While date based release numbers, using the forms ``year.month`` or
``year.month.day``, are technically compliant with this scheme, their use
is strongly discouraged as they can hinder automatic translation to
other versioning schemes. In particular, they are completely
incompatible with semantic versioning.
Semantic versioning
-------------------
`Semantic versioning`_ is a popular version identification scheme that is
more prescriptive than this PEP regarding the significance of different
elements of a release number. Even if a project chooses not to abide by
the details of semantic versioning, the scheme is worth understanding as
it covers many of the issues that can arise when depending on other
distributions, and when publishing a distribution that others rely on.
The "Major.Minor.Patch" (described in this PEP as "major.minor.micro")
aspects of semantic versioning (clauses 1-9 in the 2.0.0-rc-1 specification)
are fully compatible with the version scheme defined in this PEP, and abiding
by these aspects is encouraged.
Semantic versions containing a hyphen (pre-releases - clause 10) or a
plus sign (builds - clause 11) are *not* compatible with this PEP
and are not permitted in compliant metadata. Use this PEP's deliberately
more restricted pre-release and developmental release notation instead.
.. _Semantic versioning: http://semver.org/
Pre-releases
------------
Some projects use an "alpha, beta, release candidate" pre-release cycle to
support testing by their users prior to a full release.
If used as part of a project's development cycle, these pre-releases are
indicated by a suffix appended directly to the last component of the
release number::
X.YaN # Alpha release
X.YbN # Beta release
X.YcN # Release candidate (alternative notation: X.YrcN)
X.Y # Full release
The pre-release suffix consists of an alphabetical identifier for the
pre-release phase, along with a non-negative integer value. Pre-releases for
a given release are ordered first by phase (alpha, beta, release candidate)
and then by the numerical component within that phase.
.. note::
Using both ``c`` and ``rc`` to identify release candidates within
the scope of a single release is strongly discouraged, as it makes the
version ordering ambiguous for human readers. Automated tools should
either treat this case as an error, or else interpret all ``rc`` versions
as coming after all ``c`` versions (that is, ``rc1`` indicates a later
version than ``c2``).
Post-releases
-------------
Some projects use post-releases to address minor errors in a release that
do not affect the distributed software (for example, correcting an error
in the release notes).
If used as part of a project's development cycle, these post-releases are
indicated by a suffix appended directly to the last component of the
release number::
X.Y.postN # Post-release
The post-release suffix consists of the string ``.post``, followed by a
non-negative integer value. Post-releases are ordered by their
numerical component, immediately following the corresponding release,
and ahead of any subsequent release.
.. note::
The use of post-releases to publish maintenance releases containing
actual bug fixes is strongly discouraged. In general, it is better
to use a longer release number and increment the final component
for each maintenance release.
Post-releases are also permitted for pre-releases::
X.YaN.postM # Post-release of an alpha release
X.YbN.postM # Post-release of a beta release
X.YcN.postM # Post-release of a release candidate
.. note::
Creating post-releases of pre-releases is strongly discouraged, as
it makes the version identifier difficult to parse for human readers.
In general, it is substantially clearer to simply create a new
pre-release by incrementing the numeric component.
Developmental releases
----------------------
Some projects make regular developmental releases, and system packagers
(especially for Linux distributions) may wish to create early releases
which do not conflict with later project releases.
If used as part of a project's development cycle, these developmental
releases are indicated by a suffix appended directly to the last
component of the release number::
X.Y.devN # Developmental release
The developmental release suffix consists of the string ``.dev``,
followed by a non-negative integer value. Developmental releases are ordered
by their numerical component, immediately before the corresponding release
(and before any pre-releases), and following any previous release.
Developmental releases are also permitted for pre-releases and
post-releases::
X.YaN.devM # Developmental release of an alpha release
X.YbN.devM # Developmental release of a beta release
X.YcN.devM # Developmental release of a release candidate
X.Y.postN.devM # Developmental release of a post-release
.. note::
Creating developmental releases of pre-releases is strongly
discouraged, as it makes the version identifier difficult to parse for
human readers. In general, it is substantially clearer to simply create
a additional pre-releases by incrementing the numeric component.
Developmental releases of post-releases are also generally discouraged,
but they may be appropriate for projects which use the post-release
notation for full maintenance releases which may include code changes.
Examples of compliant version schemes
-------------------------------------
The standard version scheme is designed to encompass a wide range of
identification practices across public and private Python projects. In
practice, a single project attempting to use the full flexibility offered
by the scheme would create a situation where human users had difficulty
figuring out the relative order of versions, even though the rules above
ensure all compliant tools will order them consistently.
The following examples illustrate a small selection of the different
approaches projects may choose to identify their releases, while still
ensuring that the "latest release" and the "latest stable release" can
be easily determined, both by human users and automated tools.
Simple "major.minor" versioning::
0.1
0.2
0.3
1.0
1.1
...
Simple "major.minor.micro" versioning::
1.1.0
1.1.1
1.1.2
1.2.0
...
"major.minor" versioning with alpha, beta and release candidate
pre-releases::
0.9
1.0a1
1.0a2
1.0b1
1.0c1
1.0
1.1a1
...
"major.minor" versioning with developmental releases, release candidates
and post-releases for minor corrections::
0.9
1.0.dev1
1.0.dev2
1.0.dev3
1.0.dev4
1.0rc1
1.0rc2
1.0
1.0.post1
1.1.dev1
...
Summary of permitted suffixes and relative ordering
---------------------------------------------------
.. note::
This section is intended primarily for authors of tools that
automatically process distribution metadata, rather than authors
of Python distributions deciding on a versioning scheme.
The numeric release component of version identifiers should be sorted in
the same order as Python's tuple sorting when the release number is
parsed as follows::
tuple(map(int, release_number.split(".")))
Within a numeric release (``1.0``, ``2.7.3``), the following suffixes
are permitted and are ordered as shown::
.devN, aN, bN, cN, rcN, <no suffix>, .postN
Note that `rc` will always sort after `c` (regardless of the numeric
component) although they are semantically equivalent. Tools are free to
reject this case as ambiguous and remain in compliance with the PEP.
Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate
(``1.0c1``, ``1.0rc1``)::
(``1.0c1``, ``1.0rc1``), the following suffixes are permitted and are
ordered as shown::
.devN, <no suffix>, .postN
Within a post release (``1.0.post1``)::
Within a post-release (``1.0.post1``), the following suffixes are permitted
and are ordered as shown::
devN, <no suffix>
@ -583,16 +862,7 @@ when used immediately following a numeric version (e.g. ``1.0.dev456``,
Within a given suffix, ordering is by the value of the numeric component.
Note that `rc` will always sort after `c` (regardless of the numeric
component) although they are semantically equivalent. It is suggested
that within a particular project you do not mix `c` and `rc`, especially
within the same numeric version.
Example version order
---------------------
::
The following example covers many of the possible combinations::
1.0.dev456
1.0a1
@ -601,6 +871,7 @@ Example version order
1.0a12
1.0b1.dev456
1.0b2
1.0b2.post345.dev456
1.0b2.post345
1.0c1.dev456
1.0c1
@ -609,81 +880,85 @@ Example version order
1.0.post456
1.1.dev1
Recommended subset
------------------
The PEP authors recommend using a subset of the allowed version scheme,
similar to http://semver.org/ but without hyphenated versions.
* Version numbers are always three positive digits ``X.Y.Z`` (Major.Minor.Patch)
* The patch version is incremented for backwards-compatible bug fixes.
* The minor version is incremented for backwards-compatible API additions.
When the minor version is incremented the patch version resets to 0.
* The major version is incremented for backwards-incompatible API changes.
When the major version is incremented the minor and patch versions
reset to 0.
* Pre-release versions ending in ``a``, ``b``, and ``c`` may be used.
* Dev- and post-release versions are discouraged. Increment the patch number
instead of issuing a post-release.
When the major version is 0, the API is not considered stable, may change at
any time, and the rules about when to increment the minor and patch version
numbers are relaxed.
Ordering across different metadata versions
-------------------------------------------
Version ordering across different metadata versions
---------------------------------------------------
Metadata v1.0 (PEP 241) and metadata v1.1 (PEP 314) do not
specify a standard version numbering or sorting scheme. This PEP does
specify a standard version identification or ordering scheme. This PEP does
not mandate any particular approach to handling such versions, but
acknowledges that the de facto standard for sorting such versions is
acknowledges that the de facto standard for ordering them is
the scheme used by the ``pkg_resources`` component of ``setuptools``.
For metadata v1.2 (PEP 345), the recommended sort order is defined in
PEP 386.
Software that automatically processes distribution metadata may either
treat non-compliant version identifiers as an error, or attempt to normalize
them to the standard scheme. This means that projects using non-compliant
version identifiers may not be handled consistently across different tools,
even when correctly publishing the earlier metadata versions.
Package developers can help ensure consistent automated handling by
marking non-compliant versions as "hidden" on the Python Package Index
(removing them is generally undesirable, as users may be depending on
those specific versions being available).
Package users may also wish to remove non-compliant versions from any
private package indexes they control.
For metadata v1.2 (PEP 345), the version ordering described in this PEP
should be used in preference to the one defined in PEP 386.
The best way for a publisher to get predictable ordering is to excuse
non-compliant versions from sorting by hiding them on PyPI or by removing
them from any private index that is being used. Otherwise a client
may be restricted to using exact versions to get the correct or latest
version of your project.
Version specifiers
==================
A version specifier consists of a series of version clauses, separated by
commas. Each version clause consists of an optional comparison operator
followed by a version number. For example::
followed by a version identifier. For example::
0.9, >= 1.0, != 1.3.4, < 2.0
Each version number must be in the standard format described in
Each version identifier must be in the standard format described in
`Version scheme`_.
Comparison operators must be one of ``<``, ``>``, ``<=``, ``>=``, ``==``
``!=``, and ``~>``.
When no comparison operator is provided, it is equivalent to using ``==``.
The ``~>`` operator, "equal or greater in the last digit" is equivalent
to a pair of version clauses::
~> 2.3.3
is equivalent to::
>= 2.3.3, < 2.4.0
The comma (",") is equivalent to a logical **and** operator.
Whitespace between a conditional operator and the following version number
is optional, as is the whitespace around the commas.
Comparison operators must be one of ``<``, ``>``, ``<=``, ``>=``, ``==``
or ``!=``.
Pre-releases of any kind (indicated by the presence of ``dev``, ``a``,
``b``, ``c`` or ``rc`` in the version number) are implicitly excluded
from all version specifiers, *unless* a pre-release version is explicitly
mentioned in one of the clauses. For example, this specifier implicitly
excludes all pre-releases of later versions::
The ``==`` and ``!=`` operators are strict - in order to match, the
version supplied must exactly match the specified version, with no
additional trailing suffix.
However, when no comparison operator is provided along with a version
identifier ``V``, it is equivalent to using the following pair of version
clauses::
>= V, < V+1
where ``V+1`` is the next version after ``V``, as determined by
incrementing the last numeric component in ``V`` (for example, if
``V == 1.0a3``, then ``V+1 == 1.0a4``, while if ``V == 1.0``, then
``V+1 == 1.1``).
This approach makes it easy to depend on a particular release series
simply by naming it in a version specifier, without requiring any
additional annotation. For example, the following pairs of version
specifiers are equivalent::
2
>= 2, < 3
3.3
>= 3.3, < 3.4
Whitespace between a conditional operator and the following version
identifier is optional, as is the whitespace around the commas.
Pre-releases of any kind, including developmental releases, are implicitly
excluded from all version specifiers, *unless* a pre-release or developmental
developmental release is explicitly mentioned in one of the clauses. For
example, this specifier implicitly excludes all pre-releases and development
releases of later versions::
>= 1.0
@ -694,13 +969,13 @@ While these specifiers would include them::
>= 1.0, != 1.0b2
>= 1.0, < 2.0.dev123
Dependency resolution tools should use the above rules by default, but may
also allow users to request the following alternative behaviours:
Dependency resolution tools should use the above rules by default, but
should also allow users to request the following alternative behaviours:
* accept already installed pre-releases for all version specifiers
* retrieve and install available pre-releases for all version specifiers
Post releases and purely numeric releases receive no special treatment -
Post-releases and purely numeric releases receive no special treatment -
they are always included unless explicitly excluded.
Given the above rules, projects which include the ``.0`` suffix for the
@ -711,29 +986,29 @@ release of a series, by using a version string like ``2.5`` rather than
``2.5.0``, will need to use an explicit clause like ``>= 2.5, < 2.5.1`` to
refer specifically to that initial release.
Some Examples:
Some examples:
- ``Requires-Dist: zope.interface (3.1)``: any version that starts with 3.1,
* ``Requires-Dist: zope.interface (3.1)``: any version that starts with 3.1,
excluding pre-releases.
- ``Requires-Dist: zope.interface (==3.1)``: equivalent to ``Requires-Dist:
* ``Requires-Dist: zope.interface (==3.1)``: equivalent to ``Requires-Dist:
zope.interface (3.1)``.
- ``Requires-Dist: zope.interface (3.1.0)``: any version that starts with
* ``Requires-Dist: zope.interface (3.1.0)``: any version that starts with
3.1.0, excluding pre-releases. Since that particular project doesn't
use more than 3 digits, it also means "only the 3.1.0 release".
- ``Requires-Python: 3``: Any Python 3 version, excluding pre-releases.
- ``Requires-Python: >=2.6,<3``: Any version of Python 2.6 or 2.7, including
post releases (if they were used for Python). It excludes pre releases of
* ``Requires-Python: 3``: Any Python 3 version, excluding pre-releases.
* ``Requires-Python: >=2.6,<3``: Any version of Python 2.6 or 2.7, including
post-releases (if they were used for Python). It excludes pre releases of
Python 3.
- ``Requires-Python: 2.6.2``: Equivalent to ">=2.6.2,<2.6.3". So this includes
* ``Requires-Python: 2.6.2``: Equivalent to ">=2.6.2,<2.6.3". So this includes
only Python 2.6.2. Of course, if Python was numbered with 4 digits, it would
include all versions of the 2.6.2 series, excluding pre-releases.
- ``Requires-Python: 2.5``: Equivalent to ">=2.5,<2.6".
- ``Requires-Dist: zope.interface (3.1,!=3.1.3)``: any version that starts with
3.1, excluding pre-releases of 3.1 *and* excluding any version that
* ``Requires-Python: 2.5``: Equivalent to ">=2.5,<2.6".
* ``Requires-Dist: zope.interface (3.1,!=3.1.3)``: any version that starts
with 3.1, excluding pre-releases of 3.1 *and* excluding any version that
starts with "3.1.3". For this particular project, this means: "any version
of the 3.1 series but not 3.1.3". This is equivalent to:
">=3.1,!=3.1.3,<3.2".
- ``Requires-Python: >=3.3a1``: Any version of Python 3.3+, including
* ``Requires-Python: >=3.3a1``: Any version of Python 3.3+, including
pre-releases like 3.4a1.
@ -910,13 +1185,14 @@ Summary of differences from \PEP 345
The rationale for major changes is given in the following sections.
Standard encoding and other format clarifications
-------------------------------------------------
Several aspects of the file format, including the expected file encoding,
were underspecified in previous versions of the metadata standard. To
simplify the process of developing interoperable tools, these details are
now explicitly specified.
make it easier to develop interoperable tools, these details are now
explicitly specified.
Changing the version scheme
@ -939,21 +1215,56 @@ tools).
Making this change should make it easier for affected existing projects to
migrate to the latest version of the metadata standard.
Furthermore, as the version scheme in use is dependent on the metadata
Another change to the version scheme is to allow single number
versions, similar to those used by non-Python projects like Mozilla
Firefox, Google Chrome and the Fedora Linux distribution. This is actually
expected to be more useful for version specifiers (allowing things like
the simple ``Requires-Python: 3`` rather than the more convoluted
``Requires-Python: >= 3.0, < 4``), but it is easier to allow it for both
version specifiers and release numbers, rather than splitting the
two definitions.
Finally, as the version scheme in use is dependent on the metadata
version, it was deemed simpler to merge the scheme definition directly into
this PEP rather than continuing to maintain it as a separate PEP. This will
also allow all of the distutils-specific elements of PEP 386 to finally be
formally rejected.
A more opinionated description of the versioning scheme
-----------------------------------------------------
As in PEP 386, the primary focus is on codifying existing practices to make
them more amenable to automation, rather than demanding that existing
projects make non-trivial changes to their workflow. However, the
standard scheme allows significantly more flexibility than is needed
for the vast majority of simple Python packages (which often don't even
need maintenance releases - many users are happy with needing to upgrade to a
new feature release to get bug fixes).
For the benefit of novice developers, and for experienced developers
wishing to better understand the various use cases, the specification
now goes into much greater detail on the components of the defined
version scheme, including examples of how each component may be used
in practice.
The PEP also explicitly guides developers in the direction of
semantic versioning (without requiring it), and discourages the use of
several aspects of the full versioning scheme that have largely been
included in order to cover esoteric corner cases in the practices of
existing projects and in repackaging software for Linux distributions.
Changing the interpretation of version specifiers
-------------------------------------------------
The previous interpretation of version specifiers made it very easy to
accidentally download a pre-release version of a dependency. This in
turn made it difficult for developers to publish pre-release versions
of software to the Python Package Index, as such an action would lead
to users inadvertently downloaded pre-release software.
of software to the Python Package Index, as leaving the package set as
public would lead to users inadvertently downloading pre-release software,
while hiding it would defeat the purpose of publishing it for user
testing.
The previous interpretation also excluded post-releases from some version
specifiers for no adequately justified reason.
@ -963,8 +1274,8 @@ accept a pre-release version as satisfying a dependency, while allowing
pre-release versions to be explicitly requested when needed.
Packaging, build and installation dependencies
----------------------------------------------
Packaging and build and installation dependencies
-------------------------------------------------
The new ``Setup-Requires-Dist`` field allows a distribution to indicate when
a dependency is needed to package, build or install the distribution, rather