Releases

Nona separates editing from serving.

Each environment has:

• one editable working configuration
• zero or more immutable releases
• one optional active release

That model lets you prepare changes safely before clients receive them.

The release model

Think of the environment in two layers:

• the Parameters page is the editable working configuration
• the Releases page is the history of immutable snapshots

Applications choose their source explicitly. Working routes read the editable configuration; release routes read immutable snapshots. A release request never falls back to the editable working configuration.

That means you can change parameters, review them, and only publish a release when you are ready.

How clients resolve versions

Release reads work like this:

• /releases/active/parameters reads the environment’s active release and returns 409 active_release_not_configured when none is active
• /releases/1.2.0/parameters reads that exact release
• /releases/1.2.x/parameters reads the highest patch in the 1.2 line

Working reads use the separate /api/environments/{environmentId}/parameters routes and do not accept a release selector.

This gives you a stable exact-version path and a practical major-minor line path.

Working configuration vs active release

Editing a parameter changes what working-source clients receive on their next fetch, whether or not a release is active. Release-source clients continue to read the selected immutable release.

The editable working configuration is where operators prepare the next release.

Clients see the source selected at construction:

• working configuration through working routes
• the active release through /releases/active/parameters routes
• the exact or line-matched release through /releases/{version}/parameters routes

Clearing the active release makes active-release reads fail with 409; clients remain on their last-known-good release snapshot after a failed refresh. Exact and line-version requests continue to resolve immutable releases, and working clients remain on working routes.

That separation is one of the main safety properties of the release system.

Create a release

In admin:

1. open a project
2. switch to the target environment
3. open Releases
4. click Create a version
5. enter a major-minor version such as 1.2
6. continue to the Parameters page
7. review or adjust the working configuration
8. click Create release

Nona normalizes the entered version to patch .0, so 1.2 becomes 1.2.0.

Creating the release stores an immutable snapshot of the current working configuration.

The CLI exposes the same create behavior:

nona releases create 1.2 --project mobile-app --environment production

The CLI sends 1.2.0 without an entries payload, so the backend performs the working-configuration snapshot.

Activate a release

Creating a release does not auto-activate it.

Activation is a separate deliberate step:

1. open Releases
2. find the release you want clients to use by default
3. click Activate

After that, clients that use the active-release route read that release.

Amend an older release line

Use Amend when you need a new patch from an older release line.

For example:

• 1.1.0 amended becomes 1.1.1
• if 1.1.1 already exists, the next amend becomes 1.1.2

In admin:

1. open Releases
2. click Amend on the source release
3. Nona loads a separate, client-side editable copy of that release’s parameters
4. Nona automatically targets the next free patch in that line
5. review or adjust the parameters in that local amend buffer
6. click Create release to send the buffer as the next patch payload

Amend does not ask you to type the patch version manually.

The equivalent CLI flow also calculates the patch and edits a local copy:

nona releases amend 1.1.0 \
  --project mobile-app \
  --environment production \
  --set Features:Checkout=false

Use --from-file for larger changes. Both CLI amend input methods publish an explicit entries payload and never use the working-configuration mutation endpoints.

Important amend behavior

Amend keeps the environment’s working configuration separate from the release being patched:

• the working configuration is not read, replaced, or mutated
• edits exist only in the local amend buffer
• Create release sends that buffer as the next patch payload
• the new patch is not automatically activated
• Cancel discards the local buffer and leaves the working configuration unchanged

Delete a release

Non-active releases can be deleted from the release list.

Deleting a release:

• removes that immutable snapshot
• does not change the editable working configuration
• requires the release to not be the active release

If the release is active, activate a different release or clear the active release first.

Good release habits

• treat the Parameters page as the workspace for the next release
• activate releases separately from creating them
• use exact versions for strongly pinned consumers
• use major.minor.x line reads when clients should float to the newest patch
• amend older lines only when you intentionally want to patch that line

The line selector is part of the public client read API. Admin and CLI release-management operations require exact versions such as 1.2.0.

Practical example

One common flow looks like this:

1. production has active release 1.1.0
2. operators prepare the next working changes
3. they create version 1.2
4. Nona composes 1.2.0
5. they create the release
6. they activate 1.2.0 when ready

Later, if 1.1.0 needs a backport fix:

1. they click Amend on 1.1.0
2. Nona targets 1.1.1
3. they adjust the parameters
4. they create 1.1.1

That keeps release lines explicit and understandable.

FAQ

Does editing parameters immediately affect clients?

Working-source clients see edits on their next fetch. Release-source clients do not: selected-release requests keep reading the selected immutable release, while active-release requests fail with 409 active_release_not_configured if none is active. Release reads never fall back to the working configuration.

Why does Create a version ask for 1.2 instead of 1.2.0?

Because the admin flow treats the first release in a line as patch .0 automatically.

That keeps version entry simpler while still storing full release versions.

Does creating a release activate it automatically?

No.

Activation is a separate explicit action.

What does Amend do?

Amend targets the next free patch in the same release line and opens a separate, client-side editable copy of the source release. The working configuration remains unchanged.

Can I patch an older release line without typing the next patch version?

Yes.

That is what Amend does automatically.

Related docs

• Environments
• Parameters and content types
• History and rollback