Release Lifecycle

FrameWorks ships as tagged platform releases. This page explains which channel a tag belongs to, what each channel promises, and which upgrades are supported. For the upgrade procedure itself, see Running Cluster Upgrades.

Channels

Every release tag is classified as stable or prerelease. The CLI and the release workflow share that classifier. The candidate channel additionally follows the newest release of either kind for staging. The release catalog embedded in the CLI declares all three channels.

Channel	Tags	Moving image tag	What it is for
`stable`	Plain `vX.Y.Z` tags	`latest`	Production releases. Fixes ship in the next stable tag. There is no separately maintained long-term line.
`candidate`	Newest release, including prereleases	None; use the versioned manifest	Isolated staging and release validation.
`rc`	Any `vX.Y.Z` tag with a prerelease suffix, such as `-rc1` or `-beta.2`	`rc`	Pre-production validation. A release candidate is superseded by the next rc or stable tag of its line.

A cluster records its channel in the cluster manifest. stable is the default. frameworks cluster upgrade follows the recorded channel when you do not name a version.

frameworks cluster set-channel candidate --manifest /etc/frameworks/cluster.yaml
frameworks cluster set-channel stable --manifest /etc/frameworks/cluster.yaml

When a tag is published, the release workflow writes the release manifest and advances channels/candidate.yaml plus either channels/stable.yaml or channels/rc.yaml in the GitOps environment repository through a pull request. Pointer updates are monotonic: a delayed release job cannot move a channel backwards.

Cadence

Tags ship when a set of changes is ready, which can mean several tags in one week during active development. FrameWorks does not maintain long-term support branches. A fix for a released line ships in the next tag of the current line, and operators pick it up with a normal release apply.

Image tags

Each platform image is published to GitHub Container Registry and Docker Hub with these tags:

Tag	Meaning
`vX.Y.Z`	Multi-architecture manifest for exactly this release.
`vX.Y.Z-amd64`, `vX.Y.Z-arm64`	Single-architecture images behind the manifest.
`latest` or `rc`	The channel’s moving tag, updated to the newest release on that channel.
`vX.Y.Z-onnx-<profile>`	Edge image variants with an ONNX runtime profile (`cuda`, `tensorrt`, `openvino`).

Clusters deploy by digest from the release manifest, not by the moving tags. The moving tags exist for evaluation and local testing.

Supported upgrade sources

The release catalog embedded in the CLI is the authority for which upgrades are safe. frameworks cluster release plan reads it before any change is made.

Lifecycle boundaries. v0.3.0 is a lifecycle boundary. The republished v0.2.96 release is the only supported in-place source for the v0.3 line. Fresh clusters bootstrap directly from the current baselines.
Minimum CLI version. Each release declares the oldest CLI that may apply it. An older CLI refuses to proceed.
Minimum source version. A release can declare min_source_version, the oldest release a cluster may run while moving to it, and the floor stays in force for later releases until one raises it. Before changing anything, cluster upgrade and cluster release apply read the version every platform service replica runs and refuse when a replica is below the floor (apply the named release first), when you ask to roll back below the floor of the release a replica runs, or when a replica’s version is not a release version. There is no override. cluster upgrade plan prints the floor for the target.
Readiness. Rollouts wait up to 150 seconds for each service to report ready on /ready (v0.3.11 and later) or /health (earlier releases). See Health and readiness.
Automatic rollback. A release can disable automatic rollback for specific services when a restored previous binary could not pass the new health contract. The release plan lists these services.
Required data migrations. A release can require data migrations to finish before a later schema phase. cluster release apply checks them and stops at the postdeploy phase until they are complete. Run and verify them with cluster data-migrate, then rerun the release apply. See Data migrations.
Backups before destructive steps. cluster release apply never requires a backup. Contract migrations (cluster migrate --phase contract) and irreversible data migrations (cluster data-migrate run) do: pass --backup with a backup that started less than an hour earlier and whose migration ledgers still match. A data migration counts as irreversible when the release that declares it lists its service under rollback_disabled, or when the service binary marks it irreversible or does not say.
Unfinished earlier releases. Before changing anything, and under --dry-run too, cluster release apply reads the migration ledgers and data-migration state. It refuses when an earlier release’s postdeploy migrations or required data migrations are not complete, and names the release to apply first. A release with no migrations leaves nothing unfinished, so it can be skipped.

How changes are announced

Release notes. The GitHub Release body is the canonical release note. Its Upgrade section lists the supported source version, the minimum CLI version, operator-managed inputs that changed, and required data migrations.
Configuration. The Configuration Reference lists, for each service with typed configuration, the release that introduced each variable and any deprecation with its replacement.
Boundaries. A new lifecycle boundary, such as a raised schema migration floor, appears in the release catalog and in the release note that introduces it.