RST Release Guidelines

Revision history

June 2018: initial revision

July 2020:

• Changed official release location from Github to Zenodo
• Added release checklist
• Removed outdated information
• Formatting changes

Background

During the SuperDARN Data Analysis Working Group (DAWG) telecon on 19 March 2018, it was agreed that guidelines should be drafted to direct the versioning and timeframe of future releases of the Radar Software Toolkit (RST). This document is a formalization of those guidelines.

Note that this document is not intended to address the testing procedure for individual commits or pull requests.

Versioning

Semantic Versioning 2.0.0 should be used as a starting point for assigning version numbers to new RST releases. Generally speaking, the version number should follow the format MAJOR.MINOR.PATCH, where

• MAJOR is incremented for a major refactoring/redesign of the entire package
• MINOR is incremented for addition of new functionality (default or optional)
• PATCH is incremented for bug fixes

As an example, the MAJOR version number was incremented from VTRST3.5 to RST4.0 when the rpkg and ROS software were removed and significant changes were made to the compilation scripts. The MINOR version number was incremented from v4.0 to v4.1 when new features were added such as FITACF3.0, the Chisham virtual height model, the PSR10 and CS10 statistical models, etc. PATCH version numbers are generally reserved for bug fixes.

If the MINOR version number is incremented, then the PATCH version number should be reset to zero. Similarly, if the MAJOR version number is incremented then both the MINOR and PATCH version numbers should be reset to zero.

Archiving

RST4.0 and later are archived on Zenodo with a citable DOI.

All previous and current versions of the RST are archived on the rst-archive repository on Github.

Release Schedule

There is no regular schedule that needs to be followed regarding new releases of the RST, except for these considerations:

• At least one month of testing should be performed on each new MAJOR release branch before merging into the master branch
• No more than 1 month of testing should be performed on each new MINOR release branch before merging into the master branch
• No more than one week of testing should be performed on each new PATCH release branch before merging into the master branch
• No more than 6 months should pass without a new MINOR release if at least one new feature has been merged into the develop branch
• No more than 3 months should pass without a new PATCH release if at least one bug fix has been merged into the develop branch. In the case of severe bugs, the PATCH release should be created and distributed as quickly as possible, but with a minimum testing period of 24 hours.

Note that commits that do not modify any functionality (e.g., updates to documentation or code comments) do not qualify as a bug fix and thus do not warrant an eventual PATCH release on their own. However, these updates should be included if a PATCH release is made.

Release Checklist

Pre-PR

1. Announce intention to create a new MAJOR/MINOR/PATCH by creating an issue on Github
2. Create the release branch:
   • MAJOR/MINOR release: create from develop branch
   • PATCH release: create from master branch and then commit the required changes directly to the new patch release branch. If the required commits have already been merged into develop, cherry-pick these commits to create the release branch.
3. Update the hardware files (including the readme file) and radar.dat file on the release branch from the hdw repository
4. Update .rst.version on the release branch

Include in PR comments

1. Create a list of the significant updates that will be included in the new release, using language that users will understand. Post this as a draft release on github as a way for other developers to review this list:
   • Go to the releases page of the repo and clicking on Draft a new release
   • In this screen, the tag version should follow the repo’s convention for tag naming, the target should be the release branch, and title and description follow from the release version and summary of significant updates.
   • NOTE, do be careful on this next point: From here click on the ‘Save draft` button and not the great publish release button. This will save the release for us later.
2. Set a deadline for testing, based on the RST release guidelines

PR Reviewing Phase

1. Recruit testers
   • Testing is usually done by DAWG members, but additional testers can be sought through the darn-users mailing list, for example
   • Make sure all supported OS’s in the installation documentation are used for testing.
2. Remind testers one week before the deadline
3. Update Zenodo metadata (.zenodo.json) based on authorship guidelines
4. Update AUTHORS.md (top-level directory of RST)

PR merged

1. Merge release branch into master branch
2. Publish and tag new release on Github based on the master branch:
   • If previously created, edit the draft release to change the target to the master branch. Then press the publish release button
   • If not previously created, see Step 6 for guidance and use the publish release button instead of save draft.
3. Obtain the DOI for the new release from Zenodo. The DOI should have been created automatically by the git/Zenodo webhook.
4. Announce new release on darn-users mailing list and DAWG website:
   • Direct users to download the software from Zenodo, not Github
   • Include the list of significant updates in the release (should use language that users will understand)
   • Remind users how to cite the RST, what documentation is available, and how to report bugs
   • Provide a link to the documentation on how to cite SuperDARN review papers, SuperDARN datasets, etc.
5. Update html documentation on gh-pages branch
6. Open a pull request to merge master branch back into develop

This procedure follows the git branching model guidelines. Note that pull requests should not be made directly from the develop branch to the master branch.