Skip to content

Build data is not used when determining instance sequence #3363

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 9, 2025
Merged

Build data is not used when determining instance sequence #3363

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
70f0916
Add info about how build data is not used when determining semver pre…
paigecalvert Jul 7, 2025
1d5a906
edits
paigecalvert Jul 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 64 additions & 49 deletions docs/vendor/releases-about.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ Replicated includes the following channels by default:

You can archive or edit any of the default channels, and create new channels. For more information, see [Create and Edit Channels](releases-creating-channels).

### Settings
### Channel Settings

Each channel has settings. You can customize the settings for a channel to control some of the behavior of releases promoted to the channel.

Expand Down Expand Up @@ -74,7 +74,15 @@ Each release is promoted to one or more channels. While you are developing and t

A release cannot be edited after it is promoted to a channel. This means that you can test a release on an internal development channel, and know with confidence that the same release will be available to your customers when you promote it to a channel where real customers are assigned.

### Properties
### Demotion

A channel release can be demoted from a channel. When a channel release is demoted, the release is no longer available for download, but is not withdrawn from environments where it was already downloaded or installed.

The demoted release's channel sequence and version are not reused. For customers, the release will appear to have been skipped. Un-demoting a release will restore its place in the channel sequence making it again available for download and installation.

For information about how to demote a release, see [Demote a Release](/vendor/releases-creating-releases#demote-a-release) in _Managing Releases with the Vendor Portal_.

### Release Properties

Each release has properties. You define release properties when you promote a release to a channel. You can edit release properties at any time from the channel **Release History** page in the Vendor Portal. For more information, see [Edit Release Properties](releases-creating-releases#edit-release-properties) in _Managing Releases with the Vendor Portal_.

Expand All @@ -100,92 +108,99 @@ As shown in the screenshot above, the release has the following properties:

* **Release notes (supports markdown)**: Detailed release notes for the release. The release notes support markdown and are shown to your customer.

### Sequencing
## About Using Semantic Versioning {#semantic-versioning}

By default, Replicated uses release sequence numbers to organize and order releases, and uses instance sequence numbers in an instance's internal version history.
Semantic Versioning (SemVer) is a commonly-used and recommended versioning strategy that provides implicit information about the backwards compatibility of each version, using the format MAJOR.MINOR.PATCH:

#### Release Sequences
![semver graphic](/images/semver-graphic.png)

In the Vendor Portal, each release is automatically assigned a unique, monotonically-increasing sequence number. You can use this number as a fallback to identify a promoted or draft release, if you do not set the `Version label` field during promotion. For more information, see [Manage Releases with the Vendor Portal](releases-creating-releases).
[View a larger version of this image](/images/semver-graphic.png)

The following graphic shows release sequence numbers in the Vendor Portal:
Using SemVer for your releases is recommended because it makes versioning more predictable for users. It also lets you enforce a consistent versioning pattern for your application in the Replicated Platform. For more information about SemVer, including how precendence is determined when comparing different versions, see [Semantic Versioning 2.0.0](https://semver.org).

<img alt="Release sequence numbers" src="/images/release-sequences.png" width="750px"/>
You can enable and disable SemVer for releases on each channel in the channel settings. When you enable SemVer on a channel, the Vendor Portal checks all releases promoted to that channel to verify that the version label is valid SemVer. For more information about how to enable SemVer on a channel, see [Enable Semantic Versioning](/vendor/releases-creating-channels#enable-semantic-versioning) in _Create and Edit Channels_.

[View a larger version of this image](/images/release-sequences.png)
For information about the Admin Console determines precendence for releases that use SemVer, see [How the Admin Console Assigns Instance Sequence](#instance-sequence-how) below.

#### Instance Sequences
## Release and Instance Sequencing

When a new version is available for upgrade, including when KOTS checks for upstream updates as well as when the user syncs their license or makes a config change, the KOTS Admin Console assigns a unique instance sequence number to that version. The instance sequence in the Admin Console starts at 0 and increments for each identifier that is returned when a new version is available.
The Vendor Portal uses release sequence numbers to organize and order releases. The Admin Console uses instance sequence numbers to organize and order an instance's internal version history.

This instance sequence is unrelated to the release sequence dispalyed in the Vendor Portal, and it is likely that the instance sequence will differ from the release sequence. Instance sequences are only tracked by KOTS instances, and the Vendor Portal has no knowledge of these numbers.
### Vendor Portal Release Sequence

The following graphic shows instance sequence numbers on the Admin Console dashboard:
In the Vendor Portal, each release is automatically assigned a unique, monotonically-increasing sequence number. You can use this number as a fallback to identify a promoted or draft release, if you do not set the `Version label` field during promotion. For more information, see [Manage Releases with the Vendor Portal](releases-creating-releases).

<img alt="Instance sequence numbers" src="/images/instance-sequences.png" width="550px"/>
The following graphic shows release sequence numbers in the Vendor Portal:

[View a larger version of this image](/images/instance-sequences.png)
<img alt="Release sequence numbers" src="/images/release-sequences.png" width="750px"/>

#### Channel Sequences
[View a larger version of this image](/images/release-sequences.png)

When a release is promoted to a channel, a channel sequence number is assigned. This unique sequence number increments by one and tracks the order in which releases were promoted to a channel. You can view the channel sequence on the **Release History** page in the Vendor Portal, as shown in the image below:
### Channel Sequence

When a release is promoted to a channel, a channel sequence number is assigned. This unique sequence number increments by one and tracks the order in which releases were promoted to a channel.

You can view the channel sequence on the **Release History** page in the Vendor Portal, as shown in the image below:

<img alt="Channel sequence on Release History page" src="/images/release-history-channel-sequence.png" width="750px"/>

[View a larger version of this image](/images/release-history-channel-sequence.png)

The channel sequence is also used in certain URLs. For example, a release with a *release sequence* of `170` can have a *channel sequence* of `125`. The air gap download URL for that release can contain `125` in the URL, even though the release sequence is `170`.

Ordering is more complex if some or all of the releases in a channel have a semantic version label and semantic versioning is enabled for the channel. For more information, see [Semantic Versioning Sequence](#semantic-versioning-sequence).

#### Semantic Versioning Sequence
### Admin Console Instance Sequence

For channels with semantic versioning enabled, the Admin Console sequences instance releases by their semantic versions instead of their promotion dates.
When a new version is available for upgrade (including when KOTS checks for upstream updates, when the user syncs their license, or when the user makes a config change) the KOTS Admin Console assigns a unique instance sequence number to that version.

If releases without a valid semantic version are already promoted to a channel, the Admin Console sorts the releases that do have semantic versions starting with the earliest version and proceeding to the latest. The releases with non-semantic versioning stay in the order of their promotion dates. For example, assume that you promote these releases in the following order to a channel:
The instance sequence in the Admin Console is unrelated to the release sequence in the Vendor Portal. Instance sequences are only tracked by KOTS instances, and the Vendor Portal has no knowledge of these numbers. It is also likely that the instance sequence number is different than the Vendor Portal release sequence.

- 1.0.0
- abc
- 0.1.0
- xyz
- 2.0.0
The following shows instance sequence numbers on the Admin Console dashboard:

Then, you enable semantic versioning on that channel. The Admin Console sequences the version history for the channel as follows:
<img alt="Instance sequence numbers" src="/images/instance-sequences.png" width="550px"/>

- 0.1.0
- 1.0.0
- abc
- xyz
- 2.0.0
[View a larger version of this image](/images/instance-sequences.png)

### Semantic Versioning
#### How the Admin Console Assigns Instance Sequence {#instance-sequence-how}

Semantic versioning is available with the Replicated KOTS v1.58.0 and later. Note the following:
The instance sequence in the Admin Console starts at 0 and increments for each identifier that is returned when a new version is available.

- For applications created in the Vendor Portal on or after February 23, 2022, semantic versioning is enabled by default on the Stable and Beta channels. Semantic versioning is disabled on the Unstable channel by default.
The Admin Console assigns instance sequence numbers using the following logic, depending on how semantic versioning is used:

- For existing applications created before February 23, 2022, semantic versioning is disabled by default on all channels.
* For channels _without_ semantic versioning (SemVer) enabled, the Admin Console sequences releases by their promotion dates.

Semantic versioning is recommended because it makes versioning more predictable for users and lets you enforce versioning so that no one uses an incorrect version.
* For channels _with_ SemVer enabled, the Admin Console sequences releases by their semantic version. For information about how precedence is determined in SemVer, see [11.
Precedence refers to how versions are compared to each other when ordered](https://semver.org/#spec-item-11) in the Semantic Versioning 2.0.0 documentation.
Copy link
Contributor Author

@paigecalvert paigecalvert Jul 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^ added this link to the info on precedence in the semver docs


To use semantic versioning:
The following shows an example of how the Admin Console sequences releases that use SemVer:

1. Enable semantic versioning on a channel, if it is not enabled by default. Click the **Edit channel settings** icon, and turn on the **Enable semantic versioning** toggle.
1. Assign a semantic version number when you promote a release.
- 2.13.0
- 2.12.1
- 2.12.0
- 2.12.0-2
- 2.12.0-1
- 2.11.0
Copy link
Contributor Author

@paigecalvert paigecalvert Jul 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^ added this from your example here https://github.com/replicated-collab/itrs-replicated/issues/233#issuecomment-3044541549


Releases promoted to a channel with semantic versioning enabled are verified to ensure that the release version label is a valid semantic version. For more information about valid semantic versions, see [Semantic Versioning 2.0.0](https://semver.org).
:::note
Build metadata in the semantic version string is ignored when determining version precedence. For example, the Admin Console interprets 2.12.0, 2.12.0+1, and 2.12.0+2 as the same version. Instead of using build metadata in your semantic version labels, Replicated recommends that you increment the patch version. Or, use pre-release identifiers. For example, 1.0.0-alpha or 1.0.0-1.
:::
Copy link
Contributor Author

@paigecalvert paigecalvert Jul 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^ added note to call out how build metadata isn't considered in precedence calculations


If you enable semantic versioning for a channel and then promote releases to it, Replicated recommends that you do not later disable semantic versioning for that channel.
* For channels with SemVer enabled where there is at least one release that does _not_ use SemVer, the Admin Console sequences the releases with semantic versioning by their version label. The release(s) with non-semantic versioning stay in the order of their promotion dates.

You can enable semantic versioning on a channel that already has releases promoted to it without semantic versioning. Any subsequently promoted releases must use semantic versioning. In this case, the channel will have releases with and without semantic version numbers. For information about how Replicated organizes these release sequences, see [Semantic Versioning Sequences](#semantic-versioning-sequence).
For example, assume that you promote these releases in the following order to a channel:

### Demotion
- 1.0.0
- abc
- 0.1.0
- xyz
- 2.0.0

A channel release can be demoted from a channel. When a channel release is demoted, the release is no longer available for download, but is not withdrawn from environments where it was already downloaded or installed.
Then, you enable SemVer on that channel. The Admin Console sequences the version history for the channel as follows:

The demoted release's channel sequence and version are not reused. For customers, the release will appear to have been skipped. Un-demoting a release will restore its place in the channel sequence making it again available for download and installation.

For information about how to demote a release, see [Demote a Release](/vendor/releases-creating-releases#demote-a-release) in _Managing Releases with the Vendor Portal_.
- 0.1.0
- 1.0.0
- abc
- xyz
- 2.0.0

## Vendor Portal Pages

Expand Down
24 changes: 23 additions & 1 deletion docs/vendor/releases-creating-channels.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ To create a channel:

1. Click **Create Channel**.

## Edit a Channel
## Edit Channel Settings

To edit the settings of an existing channel:

Expand All @@ -39,6 +39,28 @@ To edit the settings of an existing channel:

For more information about channel settings, see [Settings](releases-about#settings) in _About Channels and Releases_.

## Enable Semantic Versioning

You can enable and disable semantic versioning (SemVer) for releases on each channel. When you enable SemVer on a channel, the Vendor Portal checks all releases promoted to that channel to verify that the version label is valid SemVer.

You can enable SemVer on a channel that already has releases promoted to it that do not use semantic versioning. Any subsequently promoted releases must use semantic versioning. In this case, the channel will have releases with and without semantic version numbers. For more information, see [About Using Semantic Versioning](/vendor/releases-about#semantic-versioning) in _About Channels and Releases_.

:::note
If you enable SemVer for a channel and then promote releases to it, Replicated recommends that you do _not_ later disable SemVer for that channel.
:::

To enable semantic versioning on a channel:

1. In the Vendor Portal, go to **Channels** and click the **Edit channel settings** icon.

The **Channel settings** dialog opens. For example:

<img src="/images/channel-settings.png" alt="Channel Settings dialog in the Vendor Portal" width="500"/>

1. Enable the **Enable semantic versioning** toggle.

The next time that you promote a release to the channel, assign the release a semantic version number.

## Archive a Channel

You can archive an existing channel to prevent any new releases from being promoted to the channel.
Expand Down
Binary file added static/images/semver-graphic.png
View file
Open in desktop
Copy link
Contributor Author

@paigecalvert paigecalvert Jul 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added this graphic from the Commercial Software Distribution Lifecycle Handbook to enhance the description of what semver is

Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.