diff --git a/doc/contributing.rst b/doc/contributing.rst index 8432ebee9f39c6683e21bb520797b1e0cd675b36..ca5751c938ec8175239b11320f0140043e0e17bf 100644 --- a/doc/contributing.rst +++ b/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 diff --git a/fsl/version.py b/fsl/version.py index c2c7ec6cda2619e77b4db161536a5c0b26ae7a12..a298768cc78e91752f334c35a2356eac9b12d80b 100644 --- a/fsl/version.py +++ b/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