The purpose of this Wiki page is to explain how the software version information works in MRtrix3, and include details that may be used in response to frequent user questions.
Semantic Versioning
As of the official production release of MRtrix3 in April 2020 (version 3.0.0), MRtrix3 now follows Semantic Versioning. This means that the naming convention of new updates will remain consistent. The basic structure is as follows:
-
Major: These are updates where the first of the three numbers is incremented; i.e.
x.0.0.
Given that the changes from MRtrix version 0.2 to version 3.0.0 took over a decade, this is unlikely to occur in the near future. -
Minor: These are updates where the second of the three numbers is incremented; i.e.
3.x.0.
Such updates involve the addition of new features and/or the modification of existing features (where the outcomes of the use of those features changes). In the MRtrix3 repository, modifications that are contributed to such a pending update are made on the Git branch called “dev”. -
Patch: These are updates where the third of the three numbers is incremented; i.e.
3.0.x.
Such updates only involve the rectification of outright bugs or comparable issues, where the previous behaviour was unambiguously incorrect. In the MRtrix3 repository, modifications that are contributed to such a pending update are made on the Git branch called “master”; as such, anyone who builds MRtrix3 from the source code, and does not deviate away from the defaultmasterbranch, will in fact not be compiling the most recent update, but additionally any fixes that have been applied to that version but have not yet been tagged as another update.
As such, for scientific experiments that rely on consistency of software behaviour, one will generally want to not apply minor updates. For patch updates, users are encouraged to read in detail the changelogs that are prepared alongside each update. If there are no erroneous behaviours that may have affected one’s own experimentation, then such updates are safe to apply, and may result in greater stability in other areas. If however there has been erroneous behaviour identified and rectified in an update that may be relevant to your data, then re-processing of those data with the updated version is generally recommended.
Older software versions
Prior to the transition to Semantic Versioning, the software versions were as follows:
3.0_RC3(May 2018)3.0_RC2(July 2017)3.0_RC1(April 2017)-
0.3.x(earlier)
Note that while a tagged version “3.0_RC4” exists, this tag was generated for the purpose of testing release / deployment mechanisms, and is not intended for wider use.
Querying software version
The specific version of MRtrix3 that you have installed is reported at the very top-left of the inline help page:
$ mrconvert -help
MRtrix 3.0.3 mrconvert Aug 2 2021
mrconvert: part of the MRtrix3 package
SYNOPSIS
Perform conversion between different file types and optionally extract a
subset of the input image
USAGE
mrconvert [ options ] input output
input the input image.
output the output image.
Or alternatively you can request that information explicitly:
$ mrconvert -version
== mrconvert 3.0.3 ==
64 bit release version, built Aug 2 2021, using Eigen 3.3.9
Author(s): J-Donald Tournier (jdtournier@gmail.com) and Robert E. Smith (robert.smith@florey.edu.au)
Copyright (c) 2008-2021 the MRtrix3 contributors.
Online documentation
The MRtrix3 online documentation actually contains compiled documentation corresponding to multiple versions of MRtrix3. This can cause confusion if one looks at a version of the online documentation that differs from the version of the software actually being used.
-
By default, the online documentation will link to whatever corresponds to the most recent version of the documentation. This is also evident from the presence of string “
latest” in the hyperlink:https://mrtrix.readthedocs.io/en/latest/. This can however cause confusion if you are using a version of MRtrix3 that is older than such. -
There may be some hyperlinks present on the Internet that link to the documentation corresponding to a specific version of the software, but that version may be older than what an individual is themselves using.
The specific software version to which the documentation corresponds can be both viewed and changed, as indicated in this screenshot:
In addition, you should see the following warning if you are viewing a version of the documentation that does not correspond to the most recent version (which is appropriate if you are intentionally viewing the version of the documentation that corresponds to your installed MRtrix3 version, but may cause confusion if done accidentally):
