[Python-checkins] peps: PEP-0426 (Metadata 1.3) edits

[daniel.holth]

http://hg.python.org/peps/rev/25daa0625d1d
changeset:   4721:25daa0625d1d
user:        Daniel Holth <dholth at fastmail.fm>
date:        Fri Feb 08 23:12:01 2013 -0500
summary:
  PEP-0426 (Metadata 1.3) edits

files:
  pep-0426.txt |  65 ++++++++++++++++++++++++---------------
  1 files changed, 40 insertions(+), 25 deletions(-)


diff --git a/pep-0426.txt b/pep-0426.txt
--- a/pep-0426.txt
+++ b/pep-0426.txt
@@ -553,11 +553,10 @@
 
     N.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 must restrict themselves
-to metadata v1.1 (PEP 314) or earlier, as those versions do not mandate
-a particular versioning scheme.
-
+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.
 
 Suffixes and ordering
 ---------------------
@@ -610,29 +609,44 @@
     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
 -------------------------------------------
 
-After making a release with a given metadata version, it is assumed that
-projects will not revert to an older metadata version.
-
-Accordingly, and to allow projects with non-compliant version schemes
-to more easily migrate to the version scheme defined in this PEP,
-releases should be sorted by their declared metadata version *before*
-being sorted by the distribution version.
-
-Software that processes distribution metadata should account for the fact
-that metadata v1.0 (PEP 241) and metadata v1.1 (PEP 314) do not
+Metadata v1.0 (PEP 241) and metadata v1.1 (PEP 314) do not
 specify a standard version numbering or sorting 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
 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 (It is expected that projects where the defined PEP 386 sort
-order is incorrect will skip straight from metadata v1.1 to metadata v1.3).
+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
 ==================
@@ -647,17 +661,18 @@
 `Version scheme`_.
 
 Comparison operators must be one of ``<``, ``>``, ``<=``, ``>=``, ``==``
-and ``!=``.
+``!=``, and ``~>``.
 
-When no comparison operator is provided, it is equivalent to using the
-following pair of version clauses::
+When no comparison operator is provided, it is equivalent to using ``==``.
 
-    >= V, < V+1
+The ``~>`` operator, "equal or greater in the last digit" is equivalent
+to a pair of version clauses::
 
-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``).
+    ~> 2.3.3
+
+is equivalent to::
+
+    >= 2.3.3, < 2.4.0
 
 The comma (",") is equivalent to a logical **and** operator.
 

-- 
Repository URL: http://hg.python.org/peps