Include version epochs in PEP 440

pep-0440.txt

@@ -9,7 +9,8 @@ Status: Draft
 Type: Standards Track
 Content-Type: text/x-rst
 Created: 18 Mar 2013
-Post-History: 30 Mar 2013, 27 May 2013, 20 Jun 2013, 21 Dec 2013
+Post-History: 30 Mar 2013, 27 May 2013, 20 Jun 2013,
+              21 Dec 2013, 28 Jan 2014
 Replaces: 386
 
 
@@ -71,7 +72,7 @@ Public version identifiers
 
 Public version identifiers MUST comply with the following scheme::
 
-    N[.N]+[{a|b|c|rc}N][.postN][.devN]
+    [N:]N(.N)*[{a|b|c|rc}N][.postN][.devN]
 
 Public version identifiers MUST NOT include leading or trailing whitespace.
 
@@ -81,9 +82,10 @@ Installation tools SHOULD ignore any public versions which do not comply with
 this scheme. Installation tools MAY warn the user when non-compliant
 or ambiguous versions are detected.
 
-Public version identifiers are separated into up to four segments:
+Public version identifiers are separated into up to five segments:
 
-* Release segment: ``N[.N]+``
+* Epoch segment: ``N:``
+* Release segment: ``N(.N)*``
 * Pre-release segment: ``{a|b|c|rc}N``
 * Post-release segment: ``.postN``
 * Development release segment: ``.devN``
@@ -354,6 +356,41 @@ post-releases::
    notation for full maintenance releases which may include code changes.
 
 
+Version epochs
+--------------
+
+If included in a version identifier, the epoch appears before all other
+components, separated from the release segment by a colon::
+
+    E:X.Y  # Version identifier with epoch
+
+If no explicit epoch is given, the implicit epoch is ``0``.
+
+Most version identifiers will not include an epoch, as an explicit epoch is
+only needed if a project *changes* the way it handles version numbering in
+a way that means the normal version ordering rules will give the wrong
+answer. For example, if a project is using date based versions like
+``2014.04`` and would like to switch to semantic versions like ``1.0``, then
+the new releases would be identified as *older* than the date based releases
+when using the normal sorting scheme::
+
+    1.0
+    1.1
+    2.0
+    2013.10
+    2014.04
+
+However, by specifying an explicit epoch, the sort order can be changed
+appropriately, as all versions from a later epoch are sorted after versions
+from an earlier epoch::
+
+    2013.10
+    2014.04
+    1:1.0
+    1:1.1
+    1:2.0
+
+
 Examples of compliant version schemes
 -------------------------------------
 
@@ -435,6 +472,10 @@ Summary of permitted suffixes and relative ordering
    automatically process distribution metadata, rather than developers
    of Python distributions deciding on a versioning scheme.
 
+The epoch segment of version identifiers MUST be sorted according to the
+numeric value of the given epoch. If no epoch segment is present, the
+implicit numeric value is ``0``.
+
 The release segment of version identifiers MUST be sorted in
 the same order as Python's tuple sorting when the release segment is
 parsed as follows::
@@ -592,9 +633,9 @@ Olson timezone database versioning scheme: the year followed by a lowercase
 character indicating the version of the database within that year.
 
 This can be translated to a compliant public version identifier as
-``<year>.<serial>``, where the serial starts at zero (for the '<year>a'
+``<year>.<serial>``, where the serial starts at zero or one (for the
-release) and is incremented with each subsequent database update within the
+'<year>a' release) and is incremented with each subsequent database
-year.
+update within the year.
 
 As with other translated version identifiers, the corresponding Olson
 database version could be recorded in the source label field.
@@ -1169,6 +1210,21 @@ for ``pytz`` and any other projects with stable APIs, and at least be usable
 projects with less stable APIs.
 
 
+Adding version epochs
+---------------------
+
+Version epochs are added for the same reason they are part of other
+versioning schemes, such as those of the Fedora and Debian Linux
+distributions: to allow projects to gracefully change their approach to
+numbering releases, without having a new release appear to have a lower
+version number than previous releases and without having to change the name
+of the project.
+
+In particular, supporting version epochs allows a project that was previously
+using date based versioning to switch to semantic versioning by specifying
+a new version epoch.
+
+
 Adding direct references
 ------------------------
 
@@ -1215,6 +1271,11 @@ takes the suffix into account when comparing versions for exact matches,
 the PEP requires that the integrator suffix of the candidate version be
 ignored when no integrator suffix is present in the version specifier clause.
 
+The hyphen is chosen primarily for readability of local version identifiers.
+While the wheel format also uses hyphens as separators between components,
+the escaping rules defined in PEP 427 will convert the hyphen in a local
+version identifier to an underscore before using it in a wheel filename.
+
 This change is designed to ensure that an integrator provided version like
 ``pip 1.5-1`` will still satisfy a version specifier like ``pip (== 1.1)``.