PEP-0426 (Metadata 1.3) edits

pep-0426.txt

@@ -553,11 +553,10 @@ Version numbers must comply with the following scheme::
 
     N.N[.N]+[{a|b|c|rc}N][.postN][.devN]
 
-Version numbers which do not comply with this scheme are an error. Projects
+Version numbers which do not comply with this scheme are an
-which wish to use non-compliant version numbers must restrict themselves
+error. Projects which wish to use non-compliant version numbers may
-to metadata v1.1 (PEP 314) or earlier, as those versions do not mandate
+be heuristically normalized to this scheme and are less likely to sort
-a particular versioning scheme.
+correctly.
-
 
 Suffixes and ordering
 ---------------------
@@ -610,29 +609,44 @@ 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
 -------------------------------------------
 
-After making a release with a given metadata version, it is assumed that
+Metadata v1.0 (PEP 241) and metadata v1.1 (PEP 314) do not
-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
 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
+PEP 386.
-order is incorrect will skip straight from metadata v1.1 to metadata v1.3).
 
+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 @@ Each version number must be in the standard format described in
 `Version scheme`_.
 
 Comparison operators must be one of ``<``, ``>``, ``<=``, ``>=``, ``==``
-and ``!=``.
+``!=``, and ``~>``.
 
-When no comparison operator is provided, it is equivalent to using the
+When no comparison operator is provided, it is equivalent to using ``==``.
-following pair of version clauses::
 
-    >= 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
+    ~> 2.3.3
-incrementing the last numeric component in ``V`` (for example, if
+
-``V == 1.0a3``, then ``V+1 == 1.0a4``, while if ``V == 1.0``, then
+is equivalent to::
-``V+1 == 1.1``).
+
+    >= 2.3.3, < 2.4.0
 
 The comma (",") is equivalent to a logical **and** operator.