# Versions & releases

Let each application adopt changes deliberately.

A Design System’s release and an Application’s installed state have separate responsibilities. Releases describe a system; applications choose when to adopt its changes.

## Three ownership levels

| Owner | Responsibility |
| --- | --- |
| Workspace | Subscription and canonical catalogue entitlement |
| Design System | Canonical adoption, private components and release workflows |
| Application | One project target, exact installed versions and hashes |

## Exact versions

Each canonical component is independently versioned per target. Its version changes when that target’s distributed files change and includes a mandatory changelog. The initial v4 model covers 340 target-specific component versions.

A Design System Release is an immutable snapshot of one token version, exact canonical-target and private-component versions, and shared contract revisions. Dependencies must form a valid closure.

## Release tags and workflows

`base` is the fixed workflow root. In Self-serve, your team chooses the other tag names and their paths: for example, `base > staging` and `base > qa > production`. Each tag has one parent, so paths can branch but cannot merge or form cycles. `dev` is available as a custom name; `next` and `latest` are optional template names.

A tag points to an immutable Release snapshot. Creating a tag copies its parent's current snapshot. Promote copies the snapshot from the immediately preceding tag: promoting `production` in the example takes the snapshot from `qa`. Moving an earlier tag does not automatically move later tags. Rollback restores a snapshot recorded in that tag's own history.

Self-serve members, admins and owners can manage workflows and promote directly; these actions are recorded in the activity panel. Managed workflows remain operated by Frontfriend and retain approval requests.

An explicit tag in `frontfriend.config.js` takes precedence over the tag followed by the App. Without an explicit selection, the App's binding applies; an unbound App can use `base` automatically only when it is the sole active tag. Choose a tag when the workflow has multiple active tags. Moving a tag does not update component files already installed in an application.

## Application adoption

In the v4 release model, `init` reports available changes without overwriting installed component adoption, while an explicit `update` changes the lock. `diff` and `update` are intended for all plans. Use the CLI version that matches your release workflow.

## Check before rollout

Read the component changelogs, inspect the diff, update a test application and validate its build and interactions. An Application can intentionally lag behind its Design System release.

See [Migration](/docs/migration-v3-v4/) for existing v3 projects.