Commits

Floris Bruynooghe committed 9b3875b

Attempt expanding on the rationale for .postN.devN

Comments (0)

Files changed (1)

 
 The pseudo-format supported is::
 
-    N.N[.N]+[abc]N[.N]+[.(dev|post)N+|(devNpostN)]
+    N.N[.N]+[abc]N[.N]+[.postN][.devN]
 
 Some examples probably make it clearer::
 
     ...  < V('1.0.post456'))
     True
 
-The trailing ".dev123" is for pre-releases. The ".post123" is for
-post-releases -- which apparently is used by a number of projects out there
-(e.g. Twisted [#twisted]_). For example *after* a "1.2.0" release there might
-be a "1.2.0-r678" release. We used "post" instead of "r" because the "r" is
-ambiguous as to whether it indicates a pre- or post-release.
-Last ".post456dev623" is a development version of a post-release.
+The trailing ``.post123`` or ``.dev123`` is to allow post- or
+pre-releases.  In the pre-release case one usually "counts up" to the
+release, an example of this is the Python project itself. E.g. after a
+``2.6`` release the development snapshot of the next release would be
+called ``2.7.dev123``.
+
+In the post-release schema, used for example by Twisted [#twisted]_,
+you count away from a release.  So after a ``2.6`` release the
+development snapshot of the next release would be ``2.6.post123``.
+
+Lastly it is possible to have a development snapshot for a
+post-release.  This is a special case mostly provided to allow
+meaningful transitions from some edge cases in Setuptools versioning.
+
+XXX Check the actual requirement for this.
 
 ``verlib`` provides a ``RationalVersion`` class and a
 ``suggest_rational_version`` function.