Nick Coghlan  committed 87b0bad

Add version epochs

  • Participants
  • Parent commits 86b5535

Comments (0)

Files changed (1)

File versioning.rst

 Type: Standards Track
 Content-Type: text/x-rst
 Created: 18 Mar 2013
-Post-History: 30 Mar 2013, 27 May 2013, 20 Jun 2013
+Post-History: 30 Mar 2013, 27 May 2013, 20 Jun 2013, 21 Dec 2013
 Replaces: 386
 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.
 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``
    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
    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::
 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'
-release) and is incremented with each subsequent database update within the
+``<year>.<serial>``, where the serial starts at zero or one (for the
+'<year>a' release) and is incremented with each subsequent database
+update within the year.
 As with other translated version identifiers, the corresponding Olson
 database version could be recorded in the source label field.
 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
 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)``.