Merge branch 'master' into 'master'

Versioning

See merge request !17

doc/contributing.rst

@@ -24,27 +24,11 @@ Development model
  - Coding conventions are adhered to (unless there is good reason not to).
 
 
-Releases
---------
-
-
-A separate branch is created for each release. The name of the branch is
-``v[release]``, where ``[release]`` is the version number (see below). For
-example, the branch name for release ``1.0.0`` would be ``v1.0.0``.  Hotfixes
-may be added to these release branches. Hotfixes should be merged into the
-master branch, and then cherry-picked onto the release branch(es).
-
-
-Every release (including hotfixes) is also tagged with its version number.
-For example, the first commit in the ``v1.0.0`` branch would also be tagged
-with ``1.0.0``.
-
-
 Version number
 --------------
 
 
-The ``fslpy`` version number follows `semantic versioning
+The ``fslpy`` version number roughly follows `semantic versioning
 <http://semver.org/>`_ rules, so that dependant projects are able to perform
 compatibility testing.  The full version number string consists of three
 numbers::
@@ -60,8 +44,26 @@ numbers::
 - The ``major`` number is incremented on major feature additions, and
   backwards-incompatible changes.
 
-Additionally, a single letter (``a``, ``b``, ``c``, etc) may be appended
-to the version number, indicating a hotfix release.
+
+Releases
+--------
+
+
+A separate branch is created for each **minor** release. The name of the
+branch is ``v[major.minor]``, where ``[major.minor]`` is the first two
+components of the release version number (see below). For example, the branch
+name for minor release ``1.0`` would be ``v1.0``.
+
+
+Patches and hotfixes may be added to these release branches. These should be
+merged into the master branch, and then cherry-picked onto the release
+branch(es).
+
+
+Every release is also tagged with its full version number.  For example, the
+first release off the ``v1.0`` branch would be tagged with ``1.0.0``.
+Maintenance release to the ``v1.0`` branch would be tagged with ``1.0.1``,
+``1.0.2``, etc.
 
 
 Testing

fsl/version.py

@@ -4,13 +4,87 @@
 #
 # Author: Paul McCarthy <pauldmccarthy@gmail.com>
 #
-"""The sole purpose of this module is as a container for the ``fslpy``
-version number and information.
+"""The primary purpose of this module is as a container for the ``fslpy``
+version number. A couple of conveniense functions for comparing version
+numbers are also defined here.
 
 .. autosummary::
+   :nosignatures:
 
    __version__
+   parseVersionString
+   compareVersions
+
+
+The ``fslpy`` version number consists of three numbers, separated by a period,
+which roughly obeys the Semantic Versioning conventions (http://semver.org/):
+
+ 1. The major release number. This gets updated for major/external releases.
+
+ 2. The minor release number. This gets updated for minor/internal releases,
+    which involve new features, bug-fixes, and other updates.
+
+ 3. The point release number. This gets updated for minor/internal releases,
+    which primarily involve bug-fixes and minor changes.
 """
 
+
+import string
+
+
 __version__ = '1.0.0'
 """Current version number, as a string. """
+
+
+def parseVersionString(versionString):
+    """Parses the given version string, and returns a tuple containing
+    the individual components of the version number (see the description
+    of the :attr:`__version__` attribute).
+
+    An error is raised if the ``versionString`` is invalid.
+    """
+
+    components = versionString.split('.')
+
+    # Major, minor, and point
+    # version are always numeric
+    major, minor, point = [c for c in components]
+
+    # Early versions of FSLeyes
+    # used a letter at the end
+    # to denote a hotfix release.
+    # Don't break if we get one
+    # of these old version numbers.
+    point = point.strip(string.ascii_letters)
+
+    return [int(c) for c in [major, minor, point]]
+
+
+def compareVersions(v1, v2, ignorePoint=False):
+    """Compares the given ``fslpy`` version numbers.
+
+    :arg v1:          Version number to compare
+    :arg v2:          Version number to compare
+    :arg ignorePoint: Defaults to ``False``. If ``True``, the point release
+                      numbers are ignored in the comparison.
+
+    :returns: One of the following:
+
+                - -1 if ``v1`` < ``v2`` (i.e. ``v1`` is older than ``v2``)
+                -  0 if ``v1`` == ``v2``
+                -  0 if ``v1`` > ``v2``
+    """
+
+    v1 = parseVersionString(v1)
+    v2 = parseVersionString(v2)
+
+    if ignorePoint:
+        v1 = v1[:2]
+        v2 = v2[:2]
+
+    for p1, p2 in zip(v1, v2):
+
+        if p1 > p2: return  1
+        if p1 < p2: return -1
+
+    return 0