Merge pull request #3363 from replicatedhq/126246

Build data is not used when determining instance sequence

Author: paigecalvert

docs/enterprise/updating-app-manager.mdx

@@ -9,6 +9,8 @@ import ViewAirGapBundle from "../partials/install/_airgap-bundle-view-contents.m
 
 This topic describes how to perform updates in existing cluster installations with Replicated KOTS. It includes information about how to update applications and the version of KOTS running in the cluster.
 
+It also includes information about how the Admin Console determines version precendence. See [How the Admin Console Determines Version Precendence](/enterprise/updating-app-manager#how-the-admin-console-determines-version-precedence).
+
 ## Update an Application
 
 You can perform an application update using the KOTS Admin Console or the KOTS CLI. You can also set up automatic updates. See [Configure Automatic Updates](/enterprise/updating-apps).
@@ -141,4 +143,43 @@ To update KOTS in an existing air gap cluster:
     * `RO_PASSWORD` with the password associated with the username.
     * `NAMESPACE` with the namespace on your cluster where KOTS is installed.
 
-    For help information, run `kubectl kots admin-console upgrade -h`. 
+    For help information, run `kubectl kots admin-console upgrade -h`. 
+
+## How the Admin Console Determines Version Precedence
+
+The Admin Console uses version precedence to determine which versions are available for upgrade. Version precedence also determines the order in which versions are displayed on the **Version history** page, as shown in the example below:
+
+![Admin console version history page](/images/new-version-available.png)
+[View a larger version of this image](/images/new-version-available.png)
+
+The Admin Console uses the following logic to determine version precendence:
+
+* For channels _without_ semantic versioning (SemVer) enabled, the Admin Console sequences releases by their promotion dates and times. For example, if you promote a release with version label abc at 10:00am, and then promote a release with version label xyz at 10:15am, then version xyz has higher precedence (abc < xyz).
+
+* 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.
+
+   The following shows an example of version precendence in SemVer when pre-release fields are used: 
+
+    - 2.13.0
+    - 2.12.1
+    - 2.12.0
+    - 2.12.0-2
+    - 2.12.0-1
+    - 2.11.0
+
+    :::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.
+    :::
+
+* For channels with SemVer enabled where there are one or more releases that do _not_ use SemVer, the Admin Console determines precedence based on the semantic version when possible. The release(s) with non-semantic versions stay in the order of their promotion dates.
+
+    For example, assume that you promote these releases in the following order to a channel without SemVer enabled: 
+
+    - 1.0.0 promoted at 10:00 AM
+    - abc promoted at 10:15 AM
+    - 0.1.0 promoted at 10:30 AM
+    - xyz promoted at 10:45 AM
+    - 2.0.0 promoted at 11:00 AM
+
+    Then, you enable SemVer on that channel. The Admin Console assigns precedence as follows: 0.1.0 < 1.0.0 < abc < xyz < 2.0.0.    

docs/vendor/releases-about.mdx

@@ -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.
 
@@ -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_.
 
@@ -88,7 +96,7 @@ As shown in the screenshot above, the release has the following properties:
 
 * **Version label**: The version label for the release. Version labels have the following requirements:
 
-  * If semantic versioning is enabled for the channel, you must use a valid semantic version. For more information, see [Semantic Versioning](#semantic-versioning).
+  * If semantic versioning is enabled for the channel, you must use a valid semantic version. For more information, see [About Using Semantic Versioning](#semantic-versioning).
 
   <VersionLabelReqsHelm/>
 
@@ -100,92 +108,61 @@ 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)
+When SemVer is enabled, the Admin Console uses the version labels that you assign to releases to determine release precedence. This is important because precedence controls which versions are available to customers for upgrade. It also determines how versions are ordered on the Admin Console **Version history** page. For more information, see [How the Admin Console Determines Version Precedence](/enterprise/updating-app-manager#how-the-admin-console-determines-version-precedence) in _Performing Updates in Existing Clusters_.
 
-#### 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"/>
+
+[View a larger version of this image](/images/release-sequences.png)
+
+### Channel Sequence
 
-#### Channel Sequences
+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.
 
-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:
+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).
+### Admin Console Instance Sequence
 
-#### Semantic Versioning Sequence
+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. The instance sequence number starts at 0 and increments for each identifier that is returned when a new version is available.
 
-For channels with semantic versioning enabled, the Admin Console sequences instance releases by their semantic versions instead of their promotion dates.
+The purpose of the instance sequence number is to help the user track all new versions across upstream updates, config changes, and license syncs. Without the instance sequence number, this could be challegning as the version label does not change when the user makes config changes or syncs their license.
 
-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 number does _not_ reflect version precedence. The Admin Console determines version precedence based on either the release's version label (if semantic versioning is enabled) or based on the date and time the release was promoted (if semantic versioning is disabled). This is important because precedence controls which versions are available to customers for upgrade. It also determines how versions are ordered on the Admin Console **Version history** page. For more information, see [How the Admin Console Determines Version Precedence](/enterprise/updating-app-manager#how-the-admin-console-determines-version-precedence) in _Performing Updates in Existing Clusters_.
 
-- 1.0.0
-- abc
-- 0.1.0
-- xyz
-- 2.0.0 
+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.
 
-Then, you enable semantic versioning on that channel. The Admin Console sequences the version history for the channel as follows: 
+The following shows instance sequence numbers on the Admin Console dashboard:
 
-- 0.1.0
-- 1.0.0
-- abc
-- xyz
-- 2.0.0
-
-### Semantic Versioning
-
-Semantic versioning is available with the Replicated KOTS v1.58.0 and later. Note the following:
-
-- 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.
-
-- For existing applications created before February 23, 2022, semantic versioning is disabled by default on all channels.
-
-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.
-
-To use semantic versioning:
-
-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.
-
-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).
-
-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.
-
-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).
-
-### 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.
+<img alt="Instance sequence numbers" src="/images/instance-sequences.png" width="550px"/>
 
-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_. 
+[View a larger version of this image](/images/instance-sequences.png)
 
 ## Vendor Portal Pages
 

docs/vendor/releases-creating-channels.md

@@ -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:
 
@@ -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.