* Consolidated version numbering documentation in docs/dev/policies.txt (moved text from docs/dev/release.txt).

* Updated docutils.utils.version_identifier for Python 2.6 (docutils.VersionInfo).
* Moved code from tests/test/test_utils.py::HelperFunctionsTests.test_version_identifier to tests/test__init__.py::VersionInfoTests.test_version_identifier; uncommented lines in tests/test__init__.py::VersionInfoTests.test_version_info.
* Added new tests/test/test_utils.py::HelperFunctionsTests.test_version_identifier.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@8165 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

2 files changed, 120 insertions, 78 deletions

diff --git a/docutils/docs/dev/policies.txt b/docutils/docs/dev/policies.txt
index 4bd4e70b0..400637ac6 100644
--- a/docutils/docs/dev/policies.txt
+++ b/docutils/docs/dev/policies.txt
@@ -287,7 +287,7 @@ core**) is used for active -- but stable, fully tested, and reviewed
 
 If we need to cut a bugfix release, we'll create a **maintenance branch**
 based on the latest feature release.  For example, when Docutils 0.5 is
-released, this would be ``branches/docutils-0.5``, any existing 0.4.x
+released, this would be ``branches/docutils-0.5``, and any existing 0.4.x
 maintenance branches may be retired.  Maintenance branches will receive bug
 fixes only; no new features will be allowed here.
 
@@ -406,32 +406,117 @@ mistake is easy to fix.  That's what version control is for!
 Version Numbering
 =================
 
-Docutils version numbering uses a ``major.minor.micro`` scheme (x.y.z;
-for example, 0.4.1).
-
-**Major releases** (x.0, e.g. 1.0) will be rare, and will represent major
-changes in API, functionality, or commitment.  When Docutils reaches version
-1.0, the major APIs will be considered frozen and backward compatibility
-will become of paramount importance.
-
-Releases that change the minor number (x.y, e.g. 0.5) will be
-**feature releases**; new features from the `Docutils core`_ will be
-included.
-
-Releases that change the micro number (x.y.z, e.g. 0.4.1) will be
-**bug-fix releases**.  No new features will be introduced in these
-releases; only bug fixes will be included.
-
-This policy was adopted in October 2005, and will take effect with
-Docutils version 0.4.  Prior to version 0.4, Docutils didn't have an
-official version numbering policy, and micro releases contained both
-bug fixes and new features.
-
-See also the `Docutils Release Procedure`_, `docutils.__version__` and
-`docutils.__version_info__`.
+The version identifier ``docutils.__version__`` indicates the state of
+development of the current Docutils codebase.
+``docutils.__version__``, a text string, is a concise, `PEP
+440`_-conforming representation of the namedtuple
+``docutils.__version_info__``.
+
+.. _PEP 440: https://www.python.org/dev/peps/pep-0440/
+
+* The *release segment* ("``<major>.<minor>[.<micro>]``",
+  e.g. "0.4.1") is incremented after each official release.
+
+  **Major releases** (x.0, e.g. 1.0) will be rare, and will represent
+  major changes in API, functionality, or commitment.  When Docutils
+  reaches version 1.0, the major APIs will be considered frozen and
+  backward compatibility will become of paramount importance.  The
+  Docutils major release number is found in
+  ``docutils.__version_info__.major``.
+
+  Releases that change the minor number (x.y, e.g. 0.5) will be
+  **feature releases**; new features from the `Docutils core`_ will be
+  included.  The Docutils minor release number is found in
+  ``docutils.__version_info__.minor``.
+
+  Releases that change the micro number (x.y.z, e.g. 0.4.1) will be
+  **bug-fix releases**.  No new features will be introduced in these
+  releases; only bug fixes will be included.  The Docutils micro
+  release number is found in ``docutils.__version_info__.micro``.
+
+* The *pre-release segment* ("``[{a|b|rc}[N]]``") corresponds to the
+  `development status`_ of the repository or release. The alphabetic
+  label indicates the release level, found in
+  ``docutils.__version_info__.releaselevel``:
+
+  =======  =============  ============================================
+  Label    Release Level  Comment
+  =======  =============  ============================================
+  ``a``    alpha          To be used only after major experimental
+                          changes, to indicate an unstable codebase.
+
+  ``b``    beta           Stable but between releases. This is the
+                          default state of the repository, with serial==0.
+
+  ``rcN``  candidate      Release candidate: ready to release unless
+                          significant bugs emerge.
+
+  ..       final          (No label.) There is no pre-release segment
+                          for final releases.
+  =======  =============  ============================================
+
+  .. _development status:
+     https://en.wikipedia.org/wiki/Software_release_life_cycle
+
+  ``N`` in the *pre-release segment* is a non-negative integer serial
+  number; found in ``docutils.__version_info__.serial``. The serial
+  number is incremented whenever a new pre-release is begun. When the
+  serial number N is 0, it is omitted from the pre-release segment. 0
+  is used between releases (with the "beta" release level).
+
+* The *development release segment* (``.dev``) is in place during
+  development, and omitted for official releases and pre-releases.
+  "``.dev``" is present in ``docutils.__version__`` when
+  ``docutils.__version_info__.release`` is False, and absent from
+  ``docutils.__version__`` when ``docutils.__version_info__.release``
+  is True.
+
+Examples of ``docutils.__version__`` version identifiers, over the
+course of normal development (without branches), in chronological
+order:
+
+======================  ============================
+Release Level           Version Identifier
+======================  ============================
+final (release)         0.14
+beta (development)      0.15b.dev
+beta (release)          0.15b¹
+candidate 1 (dev.)      0.15rc1.dev
+candidate 1 (release)   0.15rc1
+candidate 2 (dev.)      0.15rc2.dev¹
+candidate 2 (release)   0.15rc2¹
+... candidate N         0.15rcN.dev¹, 0.15rcN¹
+final (dev.)            0.15.dev¹
+final (release)         0.15
+beta (dev.)             0.16b.dev
+======================  ============================
+
+¹may be skipped
+
+Policy history:
+
+* Prior to version 0.4, Docutils didn't have an official version
+  numbering policy, and micro releases contained both bug fixes and
+  new features.
+
+* An earlier version of this policy was adopted in October 2005, and
+  took effect with Docutils version 0.4.
+
+* This policy was updated in June 2017 for Docutils version 0.14. See
+  `Feature Request #50`_ and the `discussion on docutils-devel`__ from
+  May 28 to June 20 2017.
+
+  .. _Feature Request #50:
+     https://sourceforge.net/p/docutils/feature-requests/50/
+  __ https://sourceforge.net/p/docutils/mailman/message/35903816/
+
+See also the `Docutils Release Procedure`_, and
+``docutils.__version__`` & ``docutils.__version_info__`` in
+docuitls/__init__.py.
 
 .. _Docutils Release Procedure: release.html#version-numbers
 
+
 Snapshots
 =========
 
diff --git a/docutils/docs/dev/release.txt b/docutils/docs/dev/release.txt
index 3671cc851..cea1f9cf0 100644
--- a/docutils/docs/dev/release.txt
+++ b/docutils/docs/dev/release.txt
@@ -42,61 +42,15 @@ Releasing
 Version identifier
 ~~~~~~~~~~~~~~~~~~
 
-The version identifier ``docutils.__version__`` is a concise,
-`PEP 440`_-conforming representation of the namedtuple
-``docutils.__version_info__``.
-
-* The `release segment` (``<major>.<minor>[.<micro>]``)
-  is set according to the `Docutils Project Policies`_.
-
-* The `pre-release segment` (``[{a|b|rc}N]``) corresponds to the
-  `development status`_ of the repository or release.
-  It matches ``__version_info__.releaselevel``:
-
-  ======= ============ ==========================================
-  ..      releaselevel comment
-  ======= ============ ==========================================
-  ``a``   alpha        only after major experimental changes
-  ``b``   beta         default state of the repository
-  ``rcN`` candidate    ready to release unless significant bugs
-                       emerge (N is ``__version_info__.serial``)
-  ..      final        no pre-release segment
-  ======= ============ ==========================================
-
-* The `development release segment` (``.dev``) is omitted for official
-  releases and pre-releases, i.e. if ``__version_info__.release`` is True.
-
-See also `Feature Request #50`_ and the `discussion on
-docutils-devel`__ from May 28 to June 20 2017.
-
-Examples:
-
-   ============  ==============   =============
-   releaselevel  repository       release
-   ============  ==============   =============
-   final         …                0.14
-   beta          0.15b.dev        0.15b¹
-   candidate     0.15rc1.dev      0.15rc1
-   candidate     0.15rc2.dev¹     0.15rc2¹
-   final         0.15.dev         0.15
-   beta          0.16b.dev        …
-   ============  ==============   =============
-
-   ¹may be skipped
-
-
-.. _Docutils Project Policies: policies.html#version-numbers
-.. _Feature Request #50:
-   https://sourceforge.net/p/docutils/feature-requests/50/
-.. _PEP 440: https://www.python.org/dev/peps/pep-0440/
-.. _development status:
-   https://en.wikipedia.org/wiki/Software_release_life_cycle
-__ https://sourceforge.net/p/docutils/mailman/message/35903816/
+For details, see `Version Numbering in Docutils Project Policies`__.
+
+__ policies.html#version-numbering
+
 
 How to change the version identifier
 """"""""""""""""""""""""""""""""""""
 
-The `version identifier` ``docutils.__version__`` is defined in
+The *version identifier* ``docutils.__version__`` is defined in
 ``docutils/docutils/__init__.py`` and used in in the following files::
 
     docutils/setup.py
@@ -104,11 +58,11 @@ The `version identifier` ``docutils.__version__`` is defined in
     docutils/README.txt
     web/index.txt
 
-You can use the script ``set_release.sh``:
+You can use the script ``set_release.sh`` to change the version
+identifier:
 
 #. ``cd`` to the "docutils" subdirectory in the repository checkout,
 
-
 #. call ::
 
      ../sandbox/infrastructure/set_release.sh <new_version>
@@ -116,7 +70,10 @@ You can use the script ``set_release.sh``:
    where ``<new_version>`` is major.minor[.micro][<pre>][.dev].
 
 Finally change ``__version_info__`` in ``docutils/docutils/__init__.py``
-"by hand" to ensure it matches the `version identifier`_.
+**by hand** to ensure it matches the `version identifier`_.
+
+Run the test suite after changing the codebase version to ensure
+accuracy and consistency.
 
 
 Release steps