Compatibility Policy
Hephaestus follows Semantic Versioning 2.0.0. This page defines what a version number promises to operators. It covers the public contract, required upgrade actions, and supported versions. The CHANGELOG and GitHub Releases describe release contents.
The public contract
Semantic versioning applies to the surfaces an operator or API consumer depends on:
| Surface | What is covered |
|---|---|
| Database migration chain | Liquibase applies changesets in changelog order. A newer release builds on the previous schema. Follow the database migration instructions before an upgrade. |
| Runtime prerequisites | The minimum PostgreSQL major version, the required outbound network destinations, and any required external services. Adding one is a breaking change. |
| Configuration keys | Environment variables and hephaestus.* properties listed in the Configuration reference. Renames and removals are breaking changes. |
| Docker Compose interface | Service names, image names, the signed release-lock contract, and required environment variables of the published Compose files. This includes the self-hosted stack (docker/self-host/compose.yaml, see the Install guide). It also includes docker/compose.app.yaml, docker/compose.core.yaml and docker/compose.proxy.yaml, which the self-hosted stack includes. Deprecated in 0.95.0. Until 1.0.0 only: it leaves the contract in 1.0.0, as Supported deployment states. |
| REST API | The endpoints described by the published OpenAPI specification. CI checks each change against the previous release: see API compatibility. |
| Helm chart values | The values of the Helm chart, from the first release that publishes the chart. Removing or renaming a value, or changing its meaning, is a breaking change. A new optional value is a minor change. |
Other surfaces can change in any release without notice:
- Java and TypeScript internals.
- The database schema itself, as distinct from the migration chain.
- Undocumented endpoints.
- UI layout.
Version numbers
| Bump | Meaning |
|---|---|
Major (X.y.z) | You must act before or during the upgrade. Causes include required new, removed, or renamed configuration keys, manual or destructive migrations, and removed APIs. The release notes say what to do. MIGRATION.md has the details. |
Minor (x.Y.z) | New functionality. The upgrade needs no action. It can include new optional configuration keys. |
Patch (x.y.Z) | Bug and security fixes. The upgrade needs no action. |
Below 1.0.0, the Minor row above does not apply.
There are no major releases yet.
Breaking changes occur in minor releases (0.x.0 → 0.y.0), per
SemVer item 4.
A pre-1.0 minor release can require action.
The release notes state the required action.
This exception ends with the 1.0.0 release.
CI still fails on a 0.x API break until the change lists it as accepted.
- Read the release notes.
- Test the upgrade in staging first.
Database migrations
The migrate run mode applies pending changesets, in order, before the runtime roles of a release start. The release notes flag schema migrations and direct you to the required backup and upgrade instructions. Read those instructions before starting any target runtime role.
A release-specific migration procedure takes precedence over normal startup. For the native Hibernate JSON cutover, follow its procedure before starting the new runtime roles. That procedure owns the requirements to stop writers, verify the backup, apply the migration, and restart the roles.
Upgrade guarantee
From 1.0 onward, any 1.x can be upgraded to any later 1.y without intermediate releases. Use the target release's Helm chart. Follow the database migration instructions for its supported database baseline.
Before 1.0, do not assume an arbitrary older release can upgrade directly. Read the target release's migration instructions first: they may require an intermediate release or manual preparation. Existing databases that cross the PostgreSQL 18/Liquibase baseline transition must reach the v0.77.4 schema cut-point. Before the new application starts, complete the baseline synchronization runbook. The target release refuses an unsynchronized existing schema. It does not replay archived migrations.
Fresh databases initialize automatically.
Database baseline prerequisites
| Installed release | Required path to the target release |
|---|---|
| ≤ v0.77.3 | Install v0.77.4 and start it once → baseline synchronization runbook → target release |
| v0.77.4 | Baseline synchronization runbook → target release |
| ≥ v0.78.0 | The baseline is already synchronized. Follow the target release migration procedure |
The v0.81.0 migration guide entry names v1.0.0 as the target release. Use the release that you upgrade to as the target release. Synchronize with the signed image of that release, as the baseline synchronization runbook describes.
The database history, not the image tag alone, determines whether it has reached the cut-point. Startup and the runbook's synchronization command refuse nonempty migration history without the v0.77.4 final migration or the baseline tag. The refusal names v0.77.4 as the release to install first. Do not use synchronization to skip missing migrations. A fresh database needs no intermediate release.
Released migrations remain immutable. CI checks fresh initialization and selected upgrade fixtures. It does not prove that every migration is safe for every existing production dataset. Data-affecting migrations still require review and a rehearsal against a restored backup. Take a database backup before upgrading. Downgrades are not supported.
Deprecation policy
The release notes announce functionality to remove at least one minor release before its removal. That functionality continues to work until the removal release. After 1.0.0, removals occur only in major releases.
Supported deployment
From 1.0.0, the Helm chart is the only supported deployment. A Kubernetes cluster and a single host use the same chart. A single host runs k3s. Docker Compose stays for local development only.
The Docker Compose deployment is deprecated in 0.95.0. It stays supported for the rest of the 0.x releases.
The Helm chart values are in the public contract from the first release that publishes the chart. In 1.0.0, the Docker Compose interface leaves the public contract. A Compose file that is still in the repository after 1.0.0 is not supported. Before 1.0.0, a migration guide describes how to move a Compose install to the chart. ADR 0058 records the decision.
Support statement
Before 1.0.0, we support the latest release only. Support for 1.x gives the rules from 1.0.0. Fixes ship as new releases on top of the current version. There are no backport branches. If you hit a bug on an older version, upgrade to the latest release before reporting it. This mirrors comparable self-hosted products — for example, Sentry provides no dedicated self-hosted support and expects operators to upgrade regularly.
Support for 1.x
From 1.0.0, these rules apply to the Helm chart, the only supported deployment (Supported deployment).
The upgrade guarantee lets you move from any 1.x to the latest 1.y. Thus, the latest 1.x release is the supported one, and fixes ship on it.
When 2.0.0 is released, the last 1.x minor release gets security fixes for 12 months. It is the only older release that gets fixes. Those fixes ship as patch releases of that minor release. That minor release gets no new features and no other fixes. After the 12 months, 1.x is unsupported.
Docker image tags
All images (webapp, application-server, agent-pi, postgres) under
ghcr.io/hephaestus-build/ are published with:
| Tag | Meaning | Stability |
|---|---|---|
X.Y.Z | Exact release | Human-readable label. Production uses the signed digest lock |
X.Y | Latest patch of a minor release | Moves on every patch release |
latest | Latest release | Moves on every release |
main, <sha> | Unreleased development builds | Unsupported — never deploy these |
Releases published before the ls1intum → hephaestus-build organization transfer remain under
ghcr.io/ls1intum/hephaestus/ — GHCR packages do not transfer between organizations, and their
signatures name the old repository forever. security/release-identities.json in the repository
records which image namespace and signing identity each release uses.
For digest-pinned release images, see Release image lock.