Merge pull request #3647 from replicatedhq/129454

Document customer-facing required releases behavior

Author: paigecalvert

docs/partials/releases/_required-releases-description.mdx

@@ -1,6 +1,4 @@
 import ChangeChannel from "../partials/customers/_change-channel.mdx"
-import RequiredReleasesLimitations from "../partials/releases/_required-releases-limitations.mdx"
-import RequiredReleasesDescription from "../partials/releases/_required-releases-description.mdx"
 import VersionLabelReqsHelm from "../partials/releases/_version-label-reqs-helm.mdx"
 
 # About Channels and Releases
@@ -120,13 +118,44 @@ As shown in the screenshot above, the release has the following properties:
 
   <VersionLabelReqsHelm/>
 
-* **Requirements**: Select **Prevent this release from being skipped during upgrades** to mark the release as required.
+* **Requirements**: Enable **Prevent this release from being skipped during upgrades** to mark the release as required. For more information, [Required Releases](#required-releases).
 
-  <RequiredReleasesDescription/> 
+* **Release notes (supports markdown)**: Detailed release notes for the release. The release notes support markdown and are shown to your customer.
 
-  <RequiredReleasesLimitations/>
+### Required Releases
 
-* **Release notes (supports markdown)**: Detailed release notes for the release. The release notes support markdown and are shown to your customer.
+You can enable the **Prevent this release from being skipped during upgrades** release property to mark a release as required. The following describes the end customer experience for required releases in the Admin Console and Enterprise Portal:
+
+* For Embedded Cluster, KOTS existing cluster, or kURL installations, the Admin Console requires users to upgrade to the required version before they can upgrade to a later version. For example, if release version 1.1.0 is marked as required, users with 1.0.0 deployed must upgrade to 1.1.0 before they can upgrade to 1.1.1.
+
+  The following shows an example of the Admin Console **Version history** page when there is a required release:
+
+  <img alt="required release in the admin console" src="/images/admin-console-required-release.png" width="650px"/>
+
+  [View a larger version of this image](/images/admin-console-required-release.png)
+
+  As shown in the image above, the required release is labeled "Required", and the user is unable to click **Deploy** for a later version until the required version is deployed.
+
+* In the Enterprise Portal, required releases are indicated in the list of available application versions. If the user is performing an upgrade and the Enterprise Portal has awareness of the currently-installed version, then the customer is prevented from selecting any version later than the required version. For new installations, the list allows any version to be selected.
+
+  :::note
+  The Enterprise Portal does _not_ prevent users from skipping a required version.
+  
+  For Embedded Cluster, KOTS existing cluster, or kURL installations, the Admin Console enforces required releases. For Helm CLI installations, required releases are not enforced. See [Limitations](#limitations).
+  :::
+
+  ![release version list in enterprise portal](/images/enterprise-portal-required-releases.png)
+
+  [View a larger version of this image](/images/enterprise-portal-required-releases.png)
+
+#### Limitations
+
+Required releases have the following limitations:
+
+* Required releases are not enforced for Helm CLI installations. When the **Prevent this release from being skipped during upgrades** option is enabled, Helm CLI customers will see that the release is labeled as "required" in the Enterprise Portal. However, this label does not prevent users from skipping a required release version when installing with the Helm CLI.
+* After users deploy a required version, they can no longer redeploy (roll back to) versions earlier than the required version, even if `allowRollback` is true in the Application custom resource manifest. For more information, see [`allowRollback`](/reference/custom-resource-application#allowrollback) in the Application custom resource topic.
+* If you change the channel an existing customer is assigned to, the Admin Console always fetches the latest release on the new channel, regardless of any required releases on the channel. For more information, see [Channel Assignment](licenses-about#channel-assignment) in _About Customers_.
+* For installations using KOTS 1.125.2 or earlier (Embedded Cluster 2.9.0 or earlier), if you disable the **Prevent this release from being skipped during upgrades** option for a promoted release, the release will still be marked as required in the Admin Console, and users must still upgrade to the given version before they can upgrade to later versions. To skip a previously-required release during upgrades, users must first update their installation to KOTS 1.126.0 or later (Embedded Cluster 2.10.0 or later). For more information, see [Remove Release Requirement](/vendor/releases-creating-releases#remove-req) in _Manage Releases with the Vendor Portal_.
 
 ## About Using Semantic Versioning {#semantic-versioning}
 

docs/partials/releases/_required-releases-limitations.mdx

@@ -1,6 +1,3 @@
-import RequiredReleasesLimitations from "../partials/releases/_required-releases-limitations.mdx"
-import RequiredReleasesDescription from "../partials/releases/_required-releases-description.mdx"
-
 # Manage Releases with the Vendor Portal
 
 This topic describes how to use the Replicated Vendor Portal to create and promote releases, edit releases, edit release properties, and archive releases.
@@ -85,7 +82,7 @@ To edit a draft release:
 
 ## Edit Release Properties
 
-You can edit the properties of a release at any time. For more information about release properties, see [Release Properties](releases-about#release-properties) in _About Channels and Releases_.
+You can edit the properties of a release at any time. For more information about release properties, see [Release Properties](releases-about#release-properties) and [Required Releases](releases-about#required-releases) in _About Channels and Releases_.
 
 To edit release properties:
 
@@ -96,8 +93,32 @@ To edit release properties:
     <img src="/images/release-properties.png" alt="Release Properties dialog in the Vendor Portal" width="300"/>
 
     [View a larger image](/images/release-properties.png)
+
+    :::note
+    For information about disabling the **Prevent this release from being skipped during upgrades** option for a release that was previously marked as required, see [Remove Release Requirement](#remove-req) below.
+    :::
 1. Click **Update Release**.
 
+## Remove Release Requirement {#remove-req}
+
+You can disable the **Prevent this release from being skipped during upgrades** property for a release to remove the "required" label from the release in the Enterprise Portal.
+
+Additionally, for online (internet-connected) installations using KOTS 1.126.0 or later (Embedded Cluster 2.10.0 or later), the requirement is removed from the Admin Console the next time that an upstream update check occurs.
+
+For more information about working with required releases, see [Required Releases](releases-about#required-releases) in _About Channels and Releases_.
+
+To remove the requirement from a release:
+
+1. Go to **Channels**.
+1. In the channel where the release was promoted, click **Release History**.
+1. For the release sequence that you want to edit, open the dot menu and click **Edit release**.
+1. Disable the **Prevent this release from being skipped during upgrades** option.
+1. Click **Update Release**.
+
+:::note
+To skip a previously-required release during upgrades, users must first update their installation to KOTS 1.126.0 or later (Embedded Cluster 2.10.0 or later).
+:::
+
 ## Archive a Release
 
 You can archive releases to remove them from view on the **Releases** page. Archiving a release that has been promoted does _not_ remove the release from the channel's **Release History** page or prevent KOTS from downloading the archived release.