PEP 426: add Version-Scheme

pep-0426.txt

@@ -68,7 +68,7 @@ In a single Metadata 1.3 file, fields marked with "(optional)" may occur
 0 or 1 times.  Fields marked with "(multiple use)" may be specified
 0, 1 or more times.  Only "Metadata-Version", "Name", "Version", and
 "Summary" must appear exactly once.  The fields may appear in any order
-within the file.
+within the header section of the file.
 
 Metadata-Version
 ::::::::::::::::
@@ -93,8 +93,7 @@ Example::
 Version
 :::::::
 
-A string containing the distribution's version number.  This
-field should be in the format specified in PEP 386.
+A string containing the distribution's version number.
 
 Example::
 
@@ -405,7 +404,7 @@ for this field are **not** required to conform to the format
 specified in PEP 386:  they should correspond to the
 version scheme used by the external dependency.
 
-Notice that there's is no particular rule on the strings to be used.
+Notice that there is no particular rule on the strings to be used.
 
 Examples::
 
@@ -484,6 +483,27 @@ the fields is not used, the `Extension: Chili` field may appear before
 or after its declared tags `Chili/Type:` etc.
 
 
+Version-Scheme (optional)
+:::::::::::::::::::::::::
+
+A string specifying the sorting method for this distribution's version
+numbers.  Although straightforward version numbers tend to sort the same in
+each scheme, there is disagreement about how to sort patch releases and
+versions having alphanumeric components such as "1.0.0rc2" and "1.0.0pre3".
+
+    Version-Scheme: pkg_resources
+    Version-Scheme: pep386
+    Version-Scheme: semver-2.0.0rc1
+    Version-Scheme: random
+
+The four initially supported schemes are:
+
+* pkg_resources: sort according to setuptools' pkg_resources module
+* pep386: sort according to the rules in pep386
+* semver-2.0.0rc1: sort according to http://semver.org/
+* random: do the shuffle
+
+
 Version Specifiers
 ==================
 
@@ -495,7 +515,8 @@ Any number of conditional operators can be specified, e.g.
 the string ">1.0, !=1.3.4, <2.0" is a legal version declaration.
 The comma (",") is equivalent to the **and** operator.
 
-Each version number must be in the format specified in PEP 386.
+Each version number should be in the format used by the referenced
+distribution.
 
 When a version is provided, it always includes all versions that
 starts with the same value. For example the "2.5" version of Python
@@ -618,6 +639,7 @@ Summary of Differences From PEP 345
   - Provides-Extra
   - Setup-Requires-Dist
   - Obsoleted-By
+  - Version-Scheme
 
 References
 ==========