Packaging: How to create a new SCT release

Step 0: Manual QA testing

SCT contains several components that cannot be easily tested via GitHub Actions runners. So, to avoid accidentally shipping broken code, we've opted to test these elements once per release, to ensure that at least our stable releases are issue-free.

Ideally, this task should be scheduled a few weeks prior to the planned release date, in order to provide time to debug and fix issues that arise during this process.

Step 0a: GUI interfaces: Matplotlib/PyQT5

Some parts of SCT rely on PyQT5 to provide a user interface for certain tasks (e.g. sct_label_utils -create-viewer). Other parts of SCT display graphs and charts via Matplotlib's Pyplot.

While we do try to automate testing of these packages via the sct_check_dependencies command, our primary test suite is run on GitHub Actions virtual machines, which are headless (i.e. without displays).

Steps to test Matplotlib/PyQT5

• Install SCT on a number of different operating systems (minimum Ubuntu, macOS, and Windows).
  • TODO: Try to find a way to make this process easier. (Dedicated machines in the lab? VM setup instructions?)
• Run sct_check_dependencies from the command line.
• Run sct_testing the command line.

That's it!

Step 0b: GUI interfaces: FSLeyes Integration Script

SCT currently provides a FSLeyes integration script that allows users to run SCT commands via FSLeyes (a popular image viewer for NIfTI files). This script is valuable to SCT and its users, but it's not easy to programmatically test this script using our pytest test suite for multiple reasons:

• The script relies on the outer context from FSLeyes to function.
• GUI testing for WxPython requires an entirely different skillset than testing, say, a numerical script based on NumPy (and we only have so many developers on hand!)

Despite these challenges, there are potentially still some ways to automate testing of the FSLeyes script (see Issue #3875). But for now, rather than writing tests for the script, we're currently opting to manually test this script prior to release.

Steps to test the FSLeyes integration script

1. Ensure that the development version of SCT is installed on your system, and that you've checked out the latest commit on master.
2. Download and install the latest version of FSLeyes into a conda environment.
3. Run fsleyes from the command line.
4. Click "File > Run Script", then navigate to ${SCT_DIR}/contrib/fsl_integration and open sct_plugin.py.
5. Manually test out the script using the following procedure:

• Try running the scripts on typical input data (e.g. sct_testing_data). The FSLeyes integration is just a wrapper for the commands themselves, so they should function identically to how they would in our actual pytest test suite.
• Click on each button you see. Try to drag elements around. Try running a command then stopping it. Get creative! Think of outside-of-the-box ways to break it.

Once you've confirmed that typical usage is error-free, proceed to the next step.

Step 0c: Running tests from sct-testing-release

While we run many CI tests before merging every pull request, and daily on the master branch, we also have a few tests that we only run semi-manually at release time. This could be because they depend on larger/private data files, run for a long time, or require a GPU.

For the necessary code, data, and instructions to run these tests, see the sct-testing-release dataset.

Once the tests pass, continue to making the release.

Step 1: Updating the changelog

Step 1a: Proofreading the newest PRs

Look over the PRs since the last release date and check to see that they match the criteria listed below:

1. Milestones: Make sure that all relevant PRs are tagged with a milestone for the upcoming release.
   • Milestones are used to indicate which PRs should be included in the changelog.
   • Currently, we number our releases using 5.X minor releases.
   • SCT does not currently release patch versions. This is done partially because we currently have no way to upgrade an existing installation (rendering patches equivalent to minor releases), and partially because the size of our development team does not allow us to be agile enough to release quick patches.
2. Labels: Make sure that each PR is tagged with the necessary labels.
   • Each pull request should have one dark-purple label, which is used to group PRs into categories (feature, bug, enhancement, etc.).
   • Each pull request should also have one or more light-purple labels corresponding to the area of the codebase that the changes affect.
3. Titles: Make sure that PR titles are informative, and that they don't contain any redundant info (SCT function names, periods, etc.).

   • For example, a PR titled "Add single method to sct_compute_snr." that is also tagged with the "sct_compute_snr" label will come out looking like this in the changelog:

     **sct_compute_snr**: Add `single` method to sct_compute_snr..
     

     So, try to avoid these duplicate-information formatting issues!

Step 1b: Updating the changelog (CHANGES.md) with the newest PRs

Once all of the PRs have been proofread, you can manually run the "Update changelog and open a pull request" GitHub Actions workflow using the title of your milestone.

After this is run, a bot account will open a PR to automatically update the changelog, after which you can request a review to approve and merge the updated CHANGES.md file.

Step 2: Creating a release

Step 2a: Updating the release branch and creating a release

Once the changelog is updated for the release, you can then manually run the "Create release" GitHub Actions workflow using the title of your milestone.

This workflow uses a bot account to automatically perform the following steps:

• Updates the file ./requirements-freeze.txt, which contains up-to-date dependencies frozen for the release.
• Updates the file ./spinalcordtoolbox/version.txt to match the provided milestone number.
• Creates a new tag corresponding to the milestone number (e.g. 5.4) containing these two extra commits (which are not pushed to origin/master, only to the new tag).
• Creates a new GitHub release associated with the new tag.

Step 2b: Manually filling in the body of the release

A template is provided in the automatically-created release. You will need to fill out two things:

1. An overview of the most important changes. (You can look at previous releases for examples of what this looks like.)
2. The most recent batch_processing.sh results. (These can be copied and pasted from here.)

Step 3: Advertise the new release

Forums (SCT Forum: spinalcordmri.org, Neurostars: neurostars.org)

SCT forum post template

# ➤ New release: SCT vX.Y.Z

Dear SCT users,

We are happy to announce the release of [SCT vX.Y.Z](https://github.com/neuropoly/spinalcordtoolbox/releases/tag/X.Y.Z). 🎉

The most notable changes for this MAJOR/MINOR/PATCH release include:

* 

For the full list of changes included in this release, click [here](https://spinalcordtoolbox.com/en/latest/dev_section/CHANGES.html).

For installation instructions, click [here](https://spinalcordtoolbox.com/en/latest/user_section/installation.html).

If you have any questions or feature requests, please post in this forum.

Happy processing!

The Spinal Cord Toolbox Team

Neurostars forum post template

# Spinal Cord Toolbox (SCT) - New release vX.Y.Z 

Dear neuroimaging community,

We are happy to announce the release of [SCT vX.Y.Z](https://github.com/neuropoly/spinalcordtoolbox/releases/tag/X.Y.Z).

The most notable changes for this MAJOR/MINOR/PATCH release include:

* 

For the full list of changes included in this release, click [here](https://spinalcordtoolbox.com/en/latest/dev_section/CHANGES.html).

For installation instructions, click [here](https://spinalcordtoolbox.com/en/latest/user_section/installation.html).

If you have any questions or feature requests, please post in the [SCT forum](http://forum.spinalcordmri.org/c/sct).

Happy processing!

The Spinal Cord Toolbox Team

Twitter @SpinalToolbox

Twitter post template

We are happy to announce that a new version of SCT (vX.Y.Z) has been released! 🎉

Check out our announcement on @INCForg's @neuroquestion forum: https://neurostars.org/t/spinal-cord-toolbox-sct-new-release-vX-Y-Z 

Slack (Spinal Cord MRI group, BrainHack)

Slack message template

We are happy to announce that a new version of SCT (vX.Y.Z) has been released! 🎉 

Check out our announcement on SCT's forum: https://forum.spinalcordmri.org/t/new-release-sct-vX-Y-Z

Step 4: Inform users that their requests have been addressed

Some bugs and features are reported by users on the forum. These are tagged with the user requested label. You can check the closed issues filter to see which issues have been closed since the last release.

Each issue should have a corresponding SCT forum link, so if you think it is useful for them to know (e.g. they were waiting for the release), then please respond with a kind reply to the thread with a link to the new release in a comment on the post. For example:

Hello! I just wanted to inform you that this feature has now been introduced as of [SCT v5.4](https://forum.spinalcordmri.org/t/new-release-sct-v5-4). :tada:

Our userbase is small, and their needs are our top priority, so little things like this go a long way. :)