Add info about how build data is not used when determining semver precendence

Author: paigecalvert

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

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.