Release cycle#
Polaris has adopted a date-based versioning scheme called Calendar Versioning, with major releases numbered YY.MM. This is the same scheme utilised by the popular Ubuntu Linux distribution and the release of March 2024 would therefore be noted as the 24.03 release. For bug fix releases a minor version is introduced (YY.MM.DDD), where DDD denotes the number of days since the last major release.
All releases include core POLARIS binaries for Windows and Linux, as well as the latest version of Polarislib and QPolaris
Release schedule#
Starting in March 2024, major versions of Polaris are released on a fixed schedule twice a year, one in March and one in September, with bug-fixing releases made available whenever bugs are unearthed and fixed.
Although Polaris is being continuously developed, a fixed release schedule allows for a predictable cycle for all Polaris users, and establishes a cadence for testing and validation.
Feature freeze#
As major releases generally include significant new functionality which may not be as “battle-tested” as other components a “feature-freeze” is undertaken 1 month before release. This allows for adequate testing, bugfixing and release preparations.
After the feature freeze for a new version, new features are no longer allowed in the release-candidate branch and all the developers are tasked with verifying results and fixing bugs unearthed by the automated testing systems in order to stabilizing Polaris for release.
At this stage, an extensive suite of automated tests are run across a number of models being maintained and developers ideally start extensive testing of the release candidate version in their studies to verify that there are no issues. Any and all issues found are reported on the issue tracker and fixed as they get reported.
The software development team is responsible for monitoring the issue tracker and the automated model testing and assigning issues to the appropriate developer or researcher.
One week before the release, a hard freeze is initiated after which only fixes to severe problems and regressions introduced after the feature freeze are allowed in.
The software development team announces this event to all developers.
Release Process#
Two months before a release is due to be released, the planned feature set and corresponding Merge Requests which implement them are identified. This will generally be undertaken in an issue card that will be used to track progress of the relase plan. An example issue which can be used as a template can be found here: Issue 381.
The release process makes use of both git branches and git tags - an overview of this can be seen in the image below.
At the feature freeze point (approx 1 month before release date), a new branch is created from the main/develop branch with the name “vYY.MM” (i.e. v24.03). This branch should contain all the features that are planned for release. Compiled executables and wheels of this branch will be used to perform large scale regression testing against the major regional models to identify issues. Fixes for such issues will be commited as bug-fix commits directly to the release branch (these will likely be cherry-picked from develop branch as the fix is likely applicable on that branch also).
On the release date, the packaging team will tag the HEAD of the release branch with the actual version to be published (i.e. v2024.03.00) and CI/CD systems are triggered to produce the compiled executables and wheel which will be automatically uploaded to PyPi for distribution.
The packaging team are also responsible for drafting appropriate release notes which outline the major new features introduced and bug fixes/changes included. This is likely to be informed by examination of the list of merged Merge Requests (each of which comprises one commit in the main respository commit history) since the last major release. These release notes will be published to the site (http://polaris.taps.anl.gov/polaris/releases/index.html).