edits

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

@@ -96,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/>
 
@@ -120,7 +120,7 @@ Using SemVer for your releases is recommended because it makes versioning more p
 
 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_.
 
-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.
+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_.
 
 ## Release and Instance Sequencing
 
@@ -150,7 +150,11 @@ The channel sequence is also used in certain URLs. For example, a release with a
 
 ### Admin Console Instance 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.
+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.
+
+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.
+
+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_.
 
 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.
 
@@ -160,48 +164,6 @@ The following shows instance sequence numbers on the Admin Console dashboard:
 
 [View a larger version of this image](/images/instance-sequences.png)
 
-#### How the Admin Console Assigns Instance Sequence {#instance-sequence-how}
-
-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 Admin Console assigns instance sequence numbers using the following logic, depending on how semantic versioning is used:
-
-* For channels _without_ semantic versioning (SemVer) enabled, the Admin Console sequences releases by their promotion dates.
-
-* 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 how the Admin Console sequences releases that use SemVer: 
-
-    - 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 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.
-
-    For example, assume that you promote these releases in the following order to a channel: 
-
-    - 1.0.0
-    - abc
-    - 0.1.0
-    - xyz
-    - 2.0.0 
-
-    Then, you enable SemVer on that channel. The Admin Console sequences the version history for the channel as follows: 
-
-    - 0.1.0
-    - 1.0.0
-    - abc
-    - xyz
-    - 2.0.0
-
 ## Vendor Portal Pages
 
 This section provides information about the channels and releases pages in the Vendor Portal.