Skip to content

FSL release management

This page describes release management procedures for the FMRIB Software Library (FSL). Release management procedures for individual projects within FSL are described separately.

FSL versioning scheme

FSL releases are given a version number containing three or four numbers, e.g. 6.0.6, 6.0.6.2 etc. Each of the numbers in this X.Y.Z[.W] scheme are referred to as follows:

  • X: Major version
  • Y: Minor version
  • Z: Patch version
  • W: Hotfix version

Due to licensing restrictions, the major and minor versions are only changed when substantial scientific additions or changes are made to the FSL code base. So for many FSL versions, only the patch and hotfix versions are updated.

Semantically, the patch and hotfix version numbers are used as follows:

  • The patch version is updated when substantial non-scientific additions or enhancements are made to the code base, or when major updates are made to the underlying dependencies of the FSL code base.
  • The hotfix version is updated for releases involving minor changes and bugfixes.

FSL releases

FSL releases are managed at the fsl/conda/manifest repository.

The fsl-release.yml file contains a list of all FSL projects and version numbers which comprise a FSL installation. As new versions of individual FSL projects are released, the entries for those projects are updated in the fsl-release.yml file.

The fsl/conda/manifest repository contains two primary branches, main and external, and may periodically contain development/release-candidate branches. These branches are used to create three different types of FSL release:

  • Public FSL releases (e.g. FSL 6.0.6) may be created from tags on the external branch.
  • Development releases (development versions of public releases) may be created from commits on any branch.
  • Internal FSL releases (for internal use only) may be created from commits on the main branch

A new version of FSL can be released by creating a tag on the external branch of the fsl/conda/manifest repository. This will trigger a CI job which generates a manifest.json file, and a set of conda environment.yml files (one for each supported platform) from the information in the fsl-release.yml file. These are then published to the FSL release web page, and so will be available to the fslinstaller.py script.

Note that there are two types of manifest and environment file:

  • The official release manifest, containing information about past and present public FSL releases - this is always called manifest.json, and is re-generated on new public releases

  • Development manifests, containing information about one internal or development FSL release. Development manifests are generated for every internal or development release. Development manifests are named according to a standard convention described in the Internal/development FSL releases section, below.

Development manifest and environment files can be published from any branch, but the official release manifest can only be generated/published from tags.

The CI jobs for generating and publishing the manifest.json and environment.yml files comprising a FSL release are defined in the fsl/conda/manifest-rules repository.

fslinstaller.py and getfsl.sh release management

FSL is installed with a Python script called fslinstaller.py, and may optionally be installed via a shell script called getfsl.sh, which simply installs Python, and then runs fslinstaller.py.

The fslinstaller.py script is maintained at the fsl/conda/installer GitLab repository. A new version of the fslinstaller.py script can be released by running a CI / CD job at that repository called release-new-version. This job is only available on tags.

The fslinstaller.py script is also published as a conda package, and installed as part of FSL. This is managed in the same way as other FSL conda packages - the conda recipe is at the fsl/conda/fsl-installer repository.

The getfsl.sh script is maintained at the fsl/conda/manifest-rules repository. New versions of getfsl.sh can be released via the publish-getfsl-script CI / CD job on the fsl/conda/manifest repository.

FSL release management procedure

Summary:

  • New public FSL release are created by adding a tag to the external branch of the fsl/conda/manifest repository.
  • The publish-release job, on the CI pipeline for the new tag, must be manually started in order to publish the new release.

A new version of FSL is released like so:

  1. A release candidate is prepared on a separate branch (see below).

  2. The fsl-release.yml file on the external branch of the fsl/conda/manifest repository is updated with versions of all packages that are to be included in the new release.

  3. A new tag is created on the fsl/conda/manifest repository; the tag must be the version number of the new FSL release, e.g. 6.0.7.

  4. In response to the new tag, a series of jobs are automatically executed on the fsl/conda/manifest repository using GitLab CI / CD:

    a) A set of conda environment.yml files are generated, one for each supported platform/OS. These files are named fsl-<tag>_<platform>.yml, e.g. fsl-6.0.7_macos-64.yml.

    b) A file called manifest.json is generated - this file contains all of the metadata needed to install FSL on a target system - it is used by the fslinstaller.py script when FSL is installed. The manifest.json file contains information about all available FSL releases - it is re-generated every time a new version is released. A copy of this file called manifest-<tag>.json is also created, for archival/recovery purposes.

    c) After the environment and manifest files have been generated, a test installation of the new release on each supported platform is performed.

    d) The environment.yml and manifest.json files are published to the FSL release page. This step must be invoked manually, by starting the publish-release CI job.

  5. The release changelog must be added to the FSL documentation as described below.

Release candidates

When preparing for a new FSL release or internal installation, it is recommended to publish a release candidate (RC) for testing and evaluation purposes. A release candidate can be published like so:

  1. Create a release candidate (RC) branch starting from the external branch of the fsl/conda/manifest repository, e.g. rel/6.0.7.

  2. Merge changes from the main branch into the RC branch. Resolve any conflicts that arise, making sure that internal-only FSL packages are not included in the package lists. A good idea is to compare your branch with the main branch - usually the only difference should be that your branch does not contain any internal-only packages: 

    git diff origin/main HEAD

  3. Publish the environment.yml and manifest.json files that are generated from that branch. The manifest.json file will be named and published as manifest-<last-tag>.<YYYYMMDD>.<commit>.<branch>.json, e.g. manifest-6.0.6.3.20230325.5ab3fe2.rel-6-0-7.json

  4. Use the fslinstaller.py script to install the release candidate, e.g.: 

    wget https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/releases/manifest-6.0.6.3.20230325.5ab3fe2.rel-6-0-7.json
python fslinstaller.py --manifest manifest-6.0.6.3.20230325.5ab3fe2.rel-6-0-7.json

    Or use conda/mamba directly with the corresponding environment.yml files, e.g.: 

    wget https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/releases/fsl-6.0.6.3.20230325.5ab3fe2.rel-6-0-7_linux-64.yml
mamba env create -p fsl-6.0.7rc -f fsl-6.0.6.3.20230325.5ab3fe2.rel-6-0-7_linux-64.yml

  5. Test the installation.

  6. If any changes are required, make them via a separate MR into the main branch with the changes.

  7. Repeat steps 2-6 as needed.

  8. When you are happy with the RC, merge the release candidate branch into the external branch, and tag the new release.

  9. Publish the environment.yml and manifest.json files that are generated from the tag.

The process described above is used for the following reasons:

  • All changes to the manifest should occur via the main branch, to ensure that the main branch is always ahead of, and in sync with, the external branch.
  • The final state of the RC branch, before it is merged into external should be in exactly the same state as (what will become) the tagged release; this is to ensure that the FSL release which undergoes testing is identical to that which is to be released.
  • Every merge into the external branch should correspond to a tagged release; this is so that the commit and branching history of the fsl/conda/manifest repository remains easy to reason about.

Release changelog

As part of the CI pipeline executed when a new FSL release is tagged, a changelog is automatically generated by the generate-changelog job. This changelog contains the merge request and commit history of the FSL projects which were updated in the releese.

Once the FSL release has been published, the generated changelog should be added to the FSL release history section:

  1. Navigate to the generate-changelog job for the relevant CI pipeline in the GitLab web interface at the fsl/conda/manifest repository.
  2. Download and unzip the artifacts.zip file which contains the generated changelog. The file will be called FSL-<tag>-changelog.md, e.g. FSL-6.0.7-changelog.md.
  3. Edit this file - in particular, a description of newly added or removed packages may need to be manually written.
  4. Add the changelog to the docs/development/history/ folder in the FSL documentation, and an entry to the index.md file in that directory.

Internal/development FSL releases

Summary:

  • New internal FSL releases may be created by adding commits to the main branch of the fsl/conda/manifest repository
  • New development releases may be created by adding commits to any branch of the fsl/conda/manifest repository
  • In both cases, the publish-release job on the associated CI pipelines must be started manually.

When commits are added to any branch of this repository, separate manifest.json and environment.yml files are generated from the contents of fsl-release.yml and made available for download. These files are assigned a version identifier of the form <tag>.<date>.<commit>.<branch>, where:

where: - <tag> is the most recent public FSL release version identifier (e.g 6.0.7). - <date> is the date of the commit that the files are generated from, in the form YYYYMMDD. - <commit> is the short hash of the git commit that the files are generated from. - <branchname> is the name of the branch.

The released files are then named as follows, where:

  • manifest-<tag>.<date>.<commit>.<branch>.json - the development release manifest file
  • fsl-<tag>.<date>.<commit>.<branch>_<platform>.yml - FSL environment file for platform <platform>.

After they have been generated, the manifest and environment files may be published. As with public releases, the process of publishing the manifest and environment files must be manually triggered through the GitLab web interface, via the publish-release job.

The fslinstaller.py script can be used to install an internal or development release by pointing it towards the relevant manifest file, e.g.:

python fslinstaller.py --manifest https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/releases/manifest-6.0.7.20230712.c0942018.6.0.7-release-candidate.json

Associating FSL project versions with FSL release versions

To identify the version of a specific FSL project that was released as part of a specific FSL version:

  1. Go to the fsl/conda/manifest repository.
  2. Select the FSL version tag of interest, and open the fsl-release.yml file.
  3. Look up the version for the project.

FSL release management before FSL 6.0.6

Prior to FSL 6.0.6, FSL releases were managed at the fsl/FslBuildManifests repository. The FSL_SourceManifest.yaml file contained a list of source code repositories and revisions of all FSL projects which comprised a FSL installation. New FSL releases were denoted by a tag on the fsl/FslBuildManifests repository.

The bulk of FSL was built monolithically by hand, using scripts located in the fsl/distbase and mwebster/FslBuilds repositories.

FSL projects and dependencies installed into the embedded fslpython conda environment were built and released independently to the https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/channel/ conda channel, or to conda-forge. The versions of these packages were managed at the fsl/post_install repository, in the fslpython_environment.yml file.

For FSL versions prior to 6.0.6, the process followed to identify the version of a specific FSL project that was released as part of a specific FSL version differs depending on whether the project was part of the "core" FSL release, or whether the project was part of the embedded fslpython conda environment. For "core" projects, the process is similar to that described above:

  1. Go to the fsl/FslBuildManifests repository.
  2. Select the FSL version tag of interest, and open the FSL_SourceManifest.yml file.
  3. Look up the version for the project of interest.

For projects installed in the fslpython environment, follow the above steps for the fsl/post_install project, and then:

  1. Go to the fsl/post_install repository.
  2. Select the fsl/post_install version tag of interest, and open the fslpython_environment.yml file.
  3. Look up the version for the project of interest.