[Python-checkins] r76744 - peps/trunk/pep-0386.txt

[tarek.ziade]

Author: tarek.ziade
Date: Thu Dec 10 14:14:25 2009
New Revision: 76744

Log:
copy editing + more details (python-dev feedback)

Modified:
   peps/trunk/pep-0386.txt

Modified: peps/trunk/pep-0386.txt
==============================================================================
--- peps/trunk/pep-0386.txt	(original)
+++ peps/trunk/pep-0386.txt	Thu Dec 10 14:14:25 2009
@@ -18,7 +18,7 @@
 Motivation
 ==========
 
-In Python there are no real restriction yet on how a project should manage its
+In Python there are no real restrictions yet on how a project should manage its
 versions, and how they should be incremented.
 
 Distutils provides a `version` distribution meta-data field but it is freeform and
@@ -47,18 +47,18 @@
 That is why this PEP proposes, for the sake of interoperability, a standard
 schema to express version information and its comparison semantics.
 
-Furthermore, this will make OS packagers work easier when repackaging standards
-compliant distributions, as of now it can be difficult to decide how two
+Furthermore, this will make OS packagers' work easier when repackaging standards
+compliant distributions, because as of now it can be difficult to decide how two
 distribution versions compare.
 
 
 Requisites and current status
 =============================
 
-It is not in the scope of this PEP to provide a universal versioning schema intended
-to support many or all existing versioning schemas. There will always be competing
-grammars, either mandated by distro or project policies or by historical
-reasons and we cannot expect that to change.
+It is not in the scope of this PEP to provide a universal versioning schema
+intended to support all or even most of existing versioning schemas. There
+will always be competing grammars, either mandated by distro or project
+policies or by historical reasons that we cannot expect to change.
 
 The proposed schema should be able to express the usual versioning semantics,
 so it's possible to parse any alternative versioning schema and transform it
@@ -73,7 +73,7 @@
 Projects have very different versioning needs, but the following are widely
 considered important semantics:
 
-1. there should be possible to express more than one versioning level
+1. it should be possible to express more than one versioning level
    (usually this is expressed as major and minor revision and, sometimes,
    also a micro revision).
 2. most projects need special meaning versions for "pre-releases" (such as
@@ -138,8 +138,8 @@
     >>> v1 > v2
     False
 
-The problem with this is that while it allows expressing requisite any
-nesting level it doesn't allow to express special meaning versions
+The problem with this is that while it allows expressing any
+nesting level it doesn't allow giving special meaning to versions
 (pre and post-releases as well as development versions), as expressed in
 requisites 2, 3 and 4.
 
@@ -193,14 +193,15 @@
 elements to make it usable, such as development releases or post-release tags,
 as expressed in requisites 3 and 4.
 
-Also, notice that Distutils version classes are not really used in the community.
+Also, note that Distutils version classes have beed present since years
+but are not really used in the community.
 
 
 Setuptools
 ----------
 
 Setuptools provides another version comparison tool [#setuptools-version]_
-which does not enforce any rule for the version, but try to provide a better
+which does not enforce any rules for the version, but try to provide a better
 algorithm to convert the strings to sortable keys, with a ``parse_version``
 function.
 
@@ -262,7 +263,7 @@
 a particular package was using and to provide tools on top of PyPI.
 
 Distutils classes are not really used in Python projects, but the
-Setuptools function is quite spread because it's used by tools like
+Setuptools function is quite widespread because it's used by tools like
 `easy_install` [#ezinstall]_, `pip` [#pip]_ or `zc.buildout` [#zc.buildout]_
 to install dependencies of a given project.
 
@@ -288,7 +289,19 @@
 
 The pseudo-format supported is::
 
-    N.N[.N]+[abc]N[.N]+[.postN+][.devN+]
+    N.N[.N]+[{abc}N[.N]+][.postN][.devN]
+
+The real regular expression is::
+
+    expr = r"""^
+    (?P<version>\d+\.\d+)         # minimum 'N.N'
+    (?P<extraversion>(?:\.\d+)*)  # any number of extra '.N' segments
+    (?:
+        (?P<prerel>[abc])         # 'a'=alpha, 'b'=beta, 'c'=release candidate
+        (?P<prerelversion>\d+(?:\.\d+)*)
+    )?
+    (?P<postdev>(\.post(?P<post>\d+))?(\.dev(?P<dev>\d+))?)?
+    $"""
 
 Some examples probably make it clearer::
 
@@ -310,13 +323,13 @@
     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
+post-releases -- which apparently are 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, ``.post456.dev34`` indicates a dev marker for a post release, that sorts
-before a ``.post345`` marker. This can be used to do development versions
+before a ``.post456`` marker. This can be used to do development versions
 of post releases.
 
 ``verlib`` provides a ``RationalVersion`` class and a