PEP 440 updates based on user feedback

pep-0440.txt

@@ -31,7 +31,7 @@ Provisional status of this specification
 ========================================
 
 The version representation and comparison scheme described in this PEP is
-currently accepted on a provisional basis, as described in PEP 411.
+currently accepted on a provisional basis [9]_, as described in PEP 411.
 
 This status is based on feedback received on the initial releases of pip 6.0,
 and setuptools 8.0, which revealed some issues in the specification that
@@ -820,8 +820,7 @@ specifier.
 Compatible release
 ------------------
 
-A compatible release clause consists of either a version identifier without
+A compatible release clause consists of the compatible release operator ``~=``
-any comparison operator or else the compatible release operator ``~=``
 and a version identifier. It matches any candidate version that is expected
 to be compatible with the specified version.
 
@@ -839,11 +838,9 @@ This operator MUST NOT be used with a single segment version number such as
 
 For example, the following groups of version clauses are equivalent::
 
-    2.2
     ~= 2.2
     >= 2.2, == 2.*
 
-    1.4.5
     ~= 1.4.5
     >= 1.4.5, == 1.4.*
 
@@ -851,11 +848,9 @@ If a pre-release, post-release or developmental release is named in a
 compatible release clause as ``V.N.suffix``, then the suffix is ignored
 when determining the required prefix match::
 
-    2.2.post3
     ~= 2.2.post3
     >= 2.2.post3, == 2.*
 
-    1.4.5a4
     ~= 1.4.5a4
     >= 1.4.5a4, == 1.4.*
 
@@ -863,11 +858,9 @@ The padding rules for release segment comparisons means that the assumed
 degree of forward compatibility in a compatible release clause can be
 controlled by appending additional zeros to the version specifier::
 
-    2.2.0
     ~= 2.2.0
     >= 2.2.0, == 2.2.*
 
-    1.4.5.0
     ~= 1.4.5.0
     >= 1.4.5.0, == 1.4.5.*
 
@@ -989,20 +982,29 @@ Local version identifiers are NOT permitted in this version specifier.
 Exclusive ordered comparison
 ----------------------------
 
-Exclusive ordered comparisons are similar to inclusive ordered comparisons,
+The exclusive ordered comparisons ``>`` and ``<`` are similar to the inclusive
-except that the comparison operators are ``<`` and ``>`` and the clause
+ordered comparisons in that they rely on the relative position of the candidate
-MUST be effectively interpreted as implying the prefix based version
+version and the specified version given the consistent ordering defined by the
-exclusion clause ``!= V.*``.
+standard `Version scheme`_. However, they specifically exclude pre-releases,
+post-releases, and local versions of the specified version.
 
-The exclusive ordered comparison ``> V`` MUST NOT match a post-release
+The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release
-or maintenance release of the given version. Maintenance releases can be
+of the given version unless ``V`` itself is a post release. You may mandate
-permitted by using the clause ``> V.0``, while both post releases and
+that releases are later than a particular post release, including additional
-maintenance releases can be permitted by using the inclusive ordered
+post releases, by using ``>V.postN``. For example, ``>1.7`` will allow
-comparison ``>= V.post1``.
+``1.7.1`` but not ``1.7.0.post1`` and ``>1.7.post2`` will allow ``1.7.1``
+and ``1.7.0.post3`` but not ``1.7.0``.
 
-The exclusive ordered comparison ``< V`` MUST NOT match a pre-release of
+The exclusive ordered comparison ``>V`` **MUST NOT** match a local version of
-the given version, even if acceptance of pre-releases is enabled as
+the specified version.
-described in the section below.
+
+The exclusive ordered comparison ``<V`` **MUST NOT** allow a pre-release of
+the specified version unless the specified version is itself a pre-release.
+Allowing pre-releases that are earlier than, but not equal to a specific
+pre-release may be accomplished by using ``<V.rc1`` or similar.
+
+As with version matching, the release segment is zero padded as necessary to
+ensure the release segments are compared with the same length.
 
 Local version identifiers are NOT permitted in this version specifier.
 
@@ -1067,14 +1069,14 @@ specifiers - they are always included unless explicitly excluded.
 Examples
 --------
 
-* ``3.1``: version 3.1 or later, but not version 4.0 or later.
+* ``~=3.1``: version 3.1 or later, but not version 4.0 or later.
-* ``3.1.2``: version 3.1.2 or later, but not version 3.2.0 or later.
+* ``~=3.1.2``: version 3.1.2 or later, but not version 3.2.0 or later.
-* ``3.1a1``: version 3.1a1 or later, but not version 4.0 or later.
+* ``~=3.1a1``: version 3.1a1 or later, but not version 4.0 or later.
 * ``== 3.1``: specifically version 3.1 (or 3.1.0), excludes all pre-releases,
   post releases, developmental releases and any 3.1.x maintenance releases.
 * ``== 3.1.*``: any version that starts with 3.1. Equivalent to the
-  ``3.1.0`` compatible release clause.
+  ``~=3.1.0`` compatible release clause.
-* ``3.1.0, != 3.1.3``: version 3.1.0 or later, but not version 3.1.3 and
+* ``~=3.1.0, != 3.1.3``: version 3.1.0 or later, but not version 3.1.3 and
   not version 3.2.0 or later.
 
 
@@ -1182,8 +1184,9 @@ Updating the versioning specification
 The versioning specification may be updated with clarifications without
 requiring a new PEP or a change to the metadata version.
 
-Actually changing the version comparison semantics still requires a new
+Once the Provisional caveat is removed from the specification, any further
-versioning scheme and metadata version defined in new PEPs.
+changes to the version comparison semantics will require an updated
+versioning scheme defined in a new PEP.
 
 
 Summary of differences from pkg_resources.parse_version
@@ -1353,9 +1356,7 @@ depend on updates to the installation database definition along with
 improved tools for dynamic path manipulation.
 
 The trailing wildcard syntax to request prefix based version matching was
-added to make it possible to sensibly define both compatible release clauses
+added to make it possible to sensibly define compatible release clauses.
-and the desired pre- and post-release handling semantics for ``<`` and ``>``
-ordered comparison clauses.
 
 
 Support for date based version identifiers
@@ -1504,6 +1505,27 @@ reason for this is that the Wheel normalization scheme specifies that ``-``
 gets normalized to a ``_`` to enable easier parsing of the filename.
 
 
+Summary of changes to \PEP 440
+==============================
+
+The following changes were made to this PEP based on feedback received after
+the initial reference implementation was released in setuptools 8.0 and pip
+6.0:
+
+* The exclusive ordered comparisons were updated to no longer imply a ``!=V.*``
+  which was deemed to be surprising behavior which was too hard to accurately
+  describe. Instead the exclusive ordered comparisons will simply disallow
+  matching pre-releases, post-releases, and local versions of the specified
+  version (unless the specified version is itself a pre-release, post-release
+  or local version). For an extended discussion see the threads on
+  distutils-sig [6]_ [7]_.
+
+* The normalized form for release candidates was updated from 'c' to 'rc'.
+  This change was based on user feedback received when setuptools 8.0
+  started applying normalisation to the release metadata generated when
+  preparing packages for publication on PyPI [8]_.
+
+
 References
 ==========
 
@@ -1525,6 +1547,17 @@ justifications for needing such a standard can be found in PEP 386.
 .. [5] Proof of Concept: PEP 440 within pip
     https://github.com/pypa/pip/pull/1894
 
+.. [6] PEP440: foo-X.Y.Z does not satisfy "foo>X.Y"
+    https://mail.python.org/pipermail/distutils-sig/2014-December/025451.html
+
+.. [7] PEP440: >1.7 vs >=1.7
+    https://mail.python.org/pipermail/distutils-sig/2014-December/025507.html
+
+.. [8] Amend PEP 440 with Wider Feedback on Release Candidates
+   https://mail.python.org/pipermail/distutils-sig/2014-December/025409.html
+
+.. [9] Changing the status of PEP 440 to Provisional
+   https://mail.python.org/pipermail/distutils-sig/2014-December/025412.html
 
 Appendix A
 ==========