Versioning and Upgrades

The platform version is the version of the reference service, entirius-service-volkanos. The lock of that service pins every module, so one number names a set of versions that was tested together. Modules, the CMS and the storefront keep their own versions and release on their own. A service you build yourself has the versions its own lock pins. The versions of the current platform release: Status. What changed in each one: Release Notes.

Version Numbers

• Versions follow semver: MAJOR.MINOR.PATCH.
• The version of a Python package lives only in its pyproject.toml.
• Pre-releases use the Python form aN, bN, rcN (alpha, beta, release candidate). GitHub marks them as pre-releases.
• Every tag lives on master, pre-releases included.

The release process behind these rules: Releases.

What a Release Promises

A release of a Django module never changes its app label, its tables or its import path, whatever the version number says. Everything else follows semver: a major version may break an interface, and a 0.x version may change anything. Which components are still at 0.x: Status.

Where Changes Are Written

A repository records its changes in CHANGELOG.md, and the GitHub Release of a version is made from that file. Some entries carry an Upgrade subsection with the steps that version needs, for example in the CMS changelog. Not every repository has a changelog yet. Where it is missing, the GitHub releases are the record.

API Versions

The API version is part of the URL: api/{module}/v2/…. Every new endpoint is v2. The v1 endpoints are legacy: they get no new features and no generated documentation. The rules for v2: API v2 Standard.

Taking an Upgrade

A service pins its modules in pyproject.toml and uv.lock. To move one to a newer version:

1. Read the changelog entries between your version and the target, and the module’s upgrade notes where the repository has them (docs/upgrade.md). The access module’s notes, for example, include the check that every legacy API key was imported as a token (access_import_legacy_keys --check).

2. Raise the version of the package in the pyproject.toml of your service.

3. Refresh the lock. uv caches index metadata and may not see a version published a moment ago:

   uv lock --refresh-package <dist>

4. Apply the migrations:

   make migrate

5. Check the result:

   make health

Security fixes target the latest released version of each repository, and older versions only where a repository says so: see the organisation’s SECURITY.md. Staying current is the way to receive them.

Next

Releases