OSDOCS-5545: guidance for updating to a new minor version

Author: skopacz1

modules/understanding-upgrade-channels.adoc

@@ -1,9 +1,7 @@
 // Module included in the following assemblies:
 //
-// * updating/updating-cluster-within-minor.adoc
-// * updating/updating-cluster-cli.adoc
-// * updating/updating-cluster-rhel-compute.adoc
-// * updating/updating-disconnected-cluster.adoc
+// * updating/understanding-upgrade-channels-release.adoc
+
 
 [id="understanding-upgrade-channels_{context}"]
 
@@ -92,7 +90,7 @@ First, select the minor version you want for your cluster upgrade. Selecting a c
 Due to the complexity involved in planning upgrades between versions many minors apart, channels that assist in planning upgrades beyond a single EUS-to-EUS update are not offered.
 ====
 
-Second, you should choose your desired rollout strategy. You may choose to update as soon as Red Hat declares a release GA by selecting from fast channels or you may want to wait for Red Hat to promote releases to the stable channel. Update recommendations offered in the `fast-{product-version}` and `stable-{product-version}` are both fully supported and benefit equally from ongoing data analysis. The promotion delay before promoting release to the stable channel represents the only difference between the two channels. Updates to the latest z-streams are generally promoted to the stable channel within a week or two, however the delay when initially rolling out updates to the latest minor is much longer, generally 45-90 days. Please consider the promotion delay when choosing your desired channel as waiting for promotion to the stable channel may affect your scheduling plans.
+Second, you should choose your desired rollout strategy. You may choose to update as soon as Red Hat declares a release GA by selecting from fast channels or you may want to wait for Red Hat to promote releases to the stable channel. Update recommendations offered in the `fast-{product-version}` and `stable-{product-version}` are both fully supported and benefit equally from ongoing data analysis. The promotion delay before promoting a release to the stable channel represents the only difference between the two channels. Updates to the latest z-streams are generally promoted to the stable channel within a week or two, however the delay when initially rolling out updates to the latest minor is much longer, generally 45-90 days. Please consider the promotion delay when choosing your desired channel, as waiting for promotion to the stable channel may affect your scheduling plans.
 
 Additionally, there are several factors which may lead an organization to move clusters to the fast channel either permanently or temporarily including:
 

modules/update-upgrading-cli.adoc

@@ -55,7 +55,7 @@ VERSION IMAGE
 +
 [NOTE]
 ====
-For details and information on how to perform an `EUS-to-EUS` channel upgrade, please refer to the 
+For details and information on how to perform an `EUS-to-EUS` channel upgrade, please refer to the
 _Preparing to perform an EUS-to-EUS upgrade_ page, listed in the Additional resources section.
 ====
 
@@ -77,6 +77,16 @@ $ oc adm upgrade channel stable-{product-version}
 ====
 For production clusters, you must subscribe to a `stable-\*`, `eus-*`, or `fast-*` channel.
 ====
++
+[NOTE]
+====
+When you are ready to move to the next minor version, choose the channel that corresponds to that minor version.
+The sooner the update channel is declared, the more effectively the cluster can recommend update paths to your target version.
+The cluster might take some time to evaluate all the possible updates that are available and offer the best update recommendations to choose from.
+Update recommendations can change over time, as they are based on what update options are available at the time.
+
+If you cannot see an update path to your target minor version, keep updating your cluster to the latest patch release for your current version until the next minor version is available in the path.
+====
 
 . Apply an update:
 ** To update to the latest version:
@@ -114,10 +124,10 @@ $ oc get clusterversion
 [source,terminal]
 ----
 
-Cluster version is <version> 
+Cluster version is <version>
 
 Upstream is unset, so the cluster will use an appropriate default.
-Channel: stable-4.10 (available channels: candidate-4.10, candidate-4.11, eus-4.10, fast-4.10, fast-4.11, stable-4.10) 
+Channel: stable-4.10 (available channels: candidate-4.10, candidate-4.11, eus-4.10, fast-4.10, fast-4.11, stable-4.10)
 
 No updates available. You may force an upgrade to a specific release image, but doing so might not be supported and might result in downtime or data loss.
 ----

modules/update-upgrading-web.adoc

@@ -30,9 +30,16 @@ link:https://access.redhat.com/downloads/content/290[in the errata section] of t
 ====
 For production clusters, you must subscribe to a `stable-\*`, `eus-*` or `fast-*` channel.
 ====
-ifdef::openshift-origin[]
-such as `stable-4`.
-endif::openshift-origin[]
++
+[NOTE]
+====
+When you are ready to move to the next minor version, choose the channel that corresponds to that minor version.
+The sooner the update channel is declared, the more effectively the cluster can recommend update paths to your target version.
+The cluster might take some time to evaluate all the possible updates that are available and offer the best update recommendations to choose from.
+Update recommendations can change over time, as they are based on what update options are available at the time.
+
+If you cannot see an update path to your target minor version, keep updating your cluster to the latest patch release for your current version until the next minor version is available in the path.
+====
 ** If the *Update status* is not *Updates available*, you cannot update your cluster.
 ** *Select channel* indicates the cluster version that your cluster is running or is updating to.
 

updating/understanding-upgrade-channels-release.adoc

@@ -6,7 +6,19 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-Update channels are tied to a minor version of {product-title}. For instance, {product-title} 4.10 update channels recommend updates to 4.10 and updates within 4.10. They also recommend updates within 4.9 and from 4.9 to 4.10 allowing all 4.9 to eventually update to 4.10, even if they do not immediately meet the minimum z-stream version requirements. They do not recommend updates to 4.11 or later releases. This strategy ensures that administrators explicitly decide to update to the next minor version of {product-title}.
+Update channels are the mechanism by which users declare the {product-title} minor version they intend to update their clusters to. They also allow users to choose the timing and level of support their updates will have through the `fast`, `stable`, `candidate`, and `eus` channel options. The Cluster Version Operator uses an update graph based on the channel declaration, along with other conditional information, to provide a list of recommended and conditional updates available to the cluster.
+
+Update channels correspond to a minor version of {product-title}. The version number in the channel represents the target minor version that the cluster will eventually be updated to, even if it is higher than the cluster's current minor version.
+
+For instance, {product-title} 4.10 update channels provide the following recommendations:
+
+* Updates within 4.10.
+* Updates within 4.9.
+* Updates from 4.9 to 4.10, allowing all 4.9 clusters to eventually update to 4.10, even if they do not immediately meet the minimum z-stream version requirements.
+* `eus-4.10` only: updates within 4.8.
+* `eus-4.10` only: updates from 4.8 to 4.9 to 4.10, allowing all 4.8 clusters to eventually update to 4.10.
+
+4.10 update channels do not recommend updates to 4.11 or later releases. This strategy ensures that administrators must explicitly decide to update to the next minor version of {product-title}.
 
 Update channels control only release selection and do not impact the version of the cluster that you install. The `openshift-install` binary file for a specific version of {product-title} always installs that version.