5.3. Release

This page is intended to provide information about our release process. First, we discuss the version formatting, after which we discuss the actual creation and distribution of a release.

5.3.1. Version format

Semantic versioning is used: Major.Minor.Patch.Pre[N].Post<n>.

Major releases update the first digit, e.g. 1.2.3 is updated to 2.0.0. This is used for releasing breaking changes: hub components and nodes of version 2.x.y are unlikely to be able to run an algorithm written for version 1.x.y. Also, the API responses may change in a way that breaks compatibility.

Minor releases update the second digit, e.g. 1.2.3 to 1.3.0. This is used for releasing new features (e.g. a new endpoint), enhancements and other changes that are compatible with all other components. Algorithms written for version 1.a.b should run on any vantage6 hub of version 1.c.d. Also, the APIs should be compatible with other minor versions - the same fields present before will be present in the new version, although new fields may be added. However, nodes and hubs of different minor versions may not be able to communicate properly. Therefore, we always recommend restarting the nodes after a hub upgrade (then, the nodes will automatically update to the new minor version).

Patch releases update the third digit, e.g. 1.2.3 to 1.2.4. This is used for bugfixes and other minor changes. Different patch releases should be compatible with each other, so a node of version 1.2.3 should be able to communicate with a vantage6 HQ of version 1.2.4.

Pre[N] is used for alpha (a), beta (b) and release candidates (rc) releases and the build number is appended (e.g. 2.0.1b1 indicates the first beta-build of version 2.0.1). These releases are used for testing before the actual release is made.

Post[N] is used for a rebuild where no code changes have been made, but where, for example, a dependency has been updated and a rebuild is required. We only use this to version the Docker images that are updated in these cases.

5.3.2. Testing a release

Before a release is made, it is tested by the development team. They go through the following steps to test a release:

  1. Create a release candidate. This process is the same as creating the actual release, except that the candidate has a ‘pre’ tag (e.g. 1.2.3rc1 for release candidate number 1 of version 1.2.3).

  2. Install the release. The release should be tested from a clean environment.

uv venv --python 3.13
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install vantage6==<version> --prerelease=allow

  1. Start hub and nodes. Start the hub and the nodes for the release candidate using a v6 sandbox network:

v6 sandbox new \
    --hq-image ghcr.io/vantage6/infrastructure/hq:<version> \
    --ui-image ghcr.io/vantage6/infrastructure/ui:<version> \
    --node-image ghcr.io/vantage6/infrastructure/node:<version> \
    --store-image ghcr.io/vantage6/infrastructure/algorithm-store:<version>

  1. Test code changes. Go through all issues that are part of the new release and test if they work as intended.

  2. Run test algorithms. The algorithm v6-feature-tester is run and checked. This algorithm checks several features to see if they are performing as expected.

  3. Update algorithms. For some releases, algorithms have to be updated, either because they no longer work in the new version of vantage6, because the algorithm tools have received patches or new featuresor, less urgently, if the algorithm store is extended so new metadata on the algorithm can be stored. Updating the algorithms is especially important for the algorithms in the community store, as these are used by the entire vantage6 community.

  4. Stop the network. After testing is finished, you can stop the network and clean up:

v6 sandbox stop
v6 sandbox remove

After these steps, the final release can be made. This process is described below.

Note

We are working on further automating the testing and release process.

5.3.3. Start the release process

To create a new release, one should go through the following steps:

  • Check out the correct branch of the vantage6 repository and pull the latest version. Make sure the branch is up-to-date.

git checkout main
git pull

  • Create a tag for the release. See Version format for more details on version names:

git tag version/x.y.z

  • Push the tag to the remote. This will trigger the release pipeline on Github:

git push origin version/x.y.z

Note

The release process is protected and can only be executed by certain people. Reach out if you have any questions regarding this.

5.3.4. The release pipeline

If you want to follow the release process, you can go to the Github release actions page and select the relevant release.

The release pipeline executes the following steps:

  1. It checks if the tag contains a valid version specification. If it does not, the process it stopped.

  2. Update the version in the repository code to the version specified in the tag and commit this back to the main branch.

  3. Build and push the Docker images and Helm charts to ghcr.io/vantage6.

  4. Create a Github release with the version number and the release notes.

  5. Upload the package to PyPi.

Note

All vantage6 infrastructure components (HQ, node, store, UI, etc.) are released at the same time, with the same version number.

The release pipeline uses a number of environment variables to, for instance, to authenticate to PyPi. These variables are listed and explained in the table below.

Table 5.3 Environment variables

Secret

Description

COMMIT_PAT

Github Personal Access Token with commit privileges. This is linked to an individual user with admin right as the commit on the main needs to bypass the protections. There is unfortunately not -yet- a good solution for this.

ADD_TO_PROJECT_PAT

Github Personal Access Token with project management privileges. This token is used to add new issues to project boards.

COVERALLS_TOKEN

Token from coveralls to post the test coverage stats.

DOCKER_TOKEN

Token used together DOCKER_USERNAME to upload the container images to ghcr.io/vantage6/infrastructure.

DOCKER_USERNAME

See DOCKER_TOKEN.

PYPI_TOKEN

Token used to upload the Python packages to PyPi.

5.3.5. Distribute release

Hub components (HQ, auth, store, UI) that are already running will automatically be upgraded to the latest version of their major release when they are restarted, unless otherwise specified in the respective configuration files. Nodes behave similarly, but instead of picking the latest version, they check which version the HQ is using and update to that (minor) version. The update to the new version happens by pulling the newly released Helm charts and Docker images.

Note that the major release is never automatically updated: for example, a node running version 4.1.0 will update to 4.1.1 or 4.2.0, but never to 5.0.0. Depending on the version of vantage6 that is being used, there is a reserved Docker image tag for distributing the upgrades. These are the following:

Tag

Description

uluru

5.x.x release

cotopaxi

4.x.x release

petronas

3.x.x release

harukas

2.x.x release

troltunga

1.x.x release

Docker images can be pulled manually with e.g.

docker pull ghcr.io/vantage6/infrastructure/server:cotopaxi
docker pull ghcr.io/vantage6/infrastructure/node:3.1.0

5.3.6. Post-release checks

After a release, there are a few checks that are performed. Most of these are only relevant if you are hosting a vantage6 hub yourself that is being automatically updated upon new releases, as is for instance the case for the Uluru community service.

For Uluru, the following checks may be performed:

  • Check that ghcr.io/vantage6 has updated images, e.g. hq:uluru, hq:uluru-live and node:uluru.

  • Check if the (live) hub version is updated. Go to: https://uluru.vantage6.ai/version. Check logs if it is not updated.

  • Release any documentation or blog posts that may not yet have been released.

  • Upgrade issue status to ‘Done’ in any relevant issue tracker.

  • Check if nodes are online, and restart them to update to the latest version if desired.