feat: JTBD audit Upgrade module — overview concept, persona cleanup, user journey

modules/upgrade/examples/snip_che-upgrading-the-chectl-management-tool.adoc

@@ -1,6 +1,7 @@
 :_content-type: SNIPPET
 
-This section describes how to upgrade the `{prod-cli}` management tool.
+[role="_abstract"]
+Update the `{prod-cli}` management tool to the latest version before upgrading {prod-short} from the command line.
 
 .Prerequisites
 

modules/upgrade/nav.adoc

@@ -2,7 +2,7 @@
 * xref:upgrading-che.adoc[]
 ** xref:specifying-the-update-approval-strategy.adoc[]
 ** xref:upgrading-che-using-the-web-console.adoc[]
+** xref:upgrading-the-chectl-management-tool.adoc[]
 ** xref:upgrading-che-using-the-cli-management-tool.adoc[]
 ** xref:upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc[]
-** xref:upgrading-the-chectl-management-tool.adoc[]
 ** xref:repairing-the-devworkspace-operator-on-openshift.adoc[]

modules/upgrade/pages/repairing-the-devworkspace-operator-on-openshift.adoc

@@ -1,15 +1,14 @@
 :_content-type: PROCEDURE
-:description: Repairing the {devworkspace} Operator on OpenShift
-:keywords: devworkspace, operator, repair
+:description: Fix a duplicate DevWorkspace Operator after an OLM restart or cluster upgrade.
+:keywords: devworkspace, operator, repair, duplicate
 :navtitle: Fix a duplicate {devworkspace} Operator after a cluster upgrade
 :page-aliases: administration-guide:repairing-the-devworkspace-operator-on-openshift.adoc
 
 [id="repairing-the-devworkspace-operator-on-openshift"]
 = Fix a duplicate {devworkspace} Operator after a cluster upgrade
 
-Under certain conditions, such as link:https://docs.openshift.com/container-platform/{ocp4-ver}/operators/understanding/olm/olm-understanding-olm.html[OLM] restart or cluster upgrade, the {prod2} Operator for {prod-short} might automatically install the {devworkspace} Operator even when it is already present on the cluster. In that case, you can repair the {devworkspace} Operator on OpenShift as follows:
-
-include::partial$snip_persona-admin.adoc[]
+[role="_abstract"]
+Fix a duplicate {devworkspace} Operator installation that can occur when an link:https://docs.openshift.com/container-platform/{ocp4-ver}/operators/understanding/olm/olm-understanding-olm.html[OLM] restart or cluster upgrade leaves multiple Operator entries in a *Replacing* or *Pending* loop.
 
 .Prerequisites
 

modules/upgrade/pages/specifying-the-update-approval-strategy.adoc

@@ -1,25 +1,23 @@
-:_content-type: ASSEMBLY
-:description: Specifying the update approval strategy
-:keywords: administration guide, upgrading-che-using-operatorhub
+:_content-type: PROCEDURE
+:description: Choose between automatic and manual update approval for the Operator.
+:keywords: upgrade, approval, automatic, manual
 :navtitle: Choose how updates are applied
 :page-aliases: administration-guide:specifying-the-update-approval-strategy.adoc, installation-guide:upgrading-che-using-operatorhub.adoc
 
 [id="specifying-the-{prod-id-short}-operator-update-approval-strategy-using-the-web-console"]
 = Choose how updates are applied
 
+[role="_abstract"]
+Choose between automatic and manual update approval for the {prod} Operator so that you control when new versions are installed on your cluster.
 
 The {prod} Operator supports two upgrade strategies:
 
-include::partial$snip_persona-admin.adoc[]
-
 `Automatic`::
 The Operator installs new updates when they become available.
 
 `Manual`::
 New updates need to be manually approved before installation begins.
 
-You can specify the update approval strategy for the {prod} Operator by using the OpenShift web console.
-
 .Prerequisites
 
 * An OpenShift web console session by a cluster administrator. See link:https://docs.openshift.com/container-platform/{ocp4-ver}/web_console/web-console.html[Accessing the web console].

modules/upgrade/pages/upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc

@@ -1,15 +1,14 @@
 :_content-type: PROCEDURE
-:description: Upgrading {prod-short} in a restricted environment
-:keywords: Upgrading {prod-short} in a restricted environment
+:description: Upgrade in a restricted environment by mirroring images and Operator catalogs.
+:keywords: upgrade, restricted, air-gapped, disconnected, mirror
 :navtitle: Upgrade in an air-gapped environment
 :page-aliases: administration-guide:upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc, installation-guide:upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc, installation-guide:upgrading-che-in-restricted-environment.adoc
 
 [id="upgrading-{prod-id-short}-using-the-cli-management-tool-in-restricted-environment"]
 = Upgrade in an air-gapped environment
 
-This section describes how to upgrade {prod} and perform minor version updates by using the CLI management tool in a restricted environment.
-
-include::partial$snip_persona-admin.adoc[]
+[role="_abstract"]
+Upgrade {prod-short} on a cluster with no internet access by mirroring updated container images and Operator catalogs to your private registry before running the upgrade.
 
 .Prerequisites
 

modules/upgrade/pages/upgrading-che-using-the-cli-management-tool.adoc

@@ -1,15 +1,14 @@
 :_content-type: PROCEDURE
-:description: Upgrading {prod-short} using the CLI management tool
-:keywords: administration guide, upgrading-che-using-the-cli-management-tool
+:description: Upgrade from the previous minor version using the CLI management tool.
+:keywords: upgrade, cli, chectl, command line
 :navtitle: Upgrade {prod-short} from the command line
 :page-aliases: administration-guide:upgrading-che-using-the-cli-management-tool.adoc, installation-guide:upgrading-che-using-the-cli-management-tool.adoc
 
 [id="upgrading-{prod-id-short}-using-the-cli-management-tool"]
 = Upgrade {prod-short} from the command line
 
-This section describes how to upgrade from the previous minor version using the CLI management tool.
-
-include::partial$snip_persona-admin.adoc[]
+[role="_abstract"]
+Upgrade {prod-short} from the previous minor version using the `{prod-cli}` management tool so that your deployment receives the latest bug fixes, security patches, and features.
 
 .Prerequisites
 

modules/upgrade/pages/upgrading-che-using-the-web-console.adoc

@@ -1,15 +1,14 @@
-:_content-type: ASSEMBLY
-:description: Upgrading {prod-short} using the OpenShift web console
-:keywords: administration guide, upgrading-che-using-operatorhub
+:_content-type: PROCEDURE
+:description: Approve a pending Operator upgrade in the OpenShift web console.
+:keywords: upgrade, web console, approve, manual
 :navtitle: Approve a pending upgrade in the web console
 :page-aliases: administration-guide:upgrading-che-using-the-web-console.adoc
 
 [id="upgrading-{prod-id-short}-using-the-openshift-web-console"]
 = Approve a pending upgrade in the web console
 
-You can manually approve an upgrade from an earlier minor version using the {prod} Operator from the Red Hat Ecosystem Catalog in the OpenShift web console.
-
-include::partial$snip_persona-admin.adoc[]
+[role="_abstract"]
+Approve a pending {prod} Operator upgrade in the OpenShift web console so that your deployment receives the latest features, bug fixes, and security patches at the time you choose.
 
 .Prerequisites
 

modules/upgrade/pages/upgrading-che.adoc

@@ -1,6 +1,6 @@
-:_content-type: ASSEMBLY
-:description: Keep your {prod-short} deployment current by upgrading to the latest version.
-:keywords: upgrade, update, migrate
+:_content-type: CONCEPT
+:description: Plan your upgrade by reviewing supported paths, choosing an approval strategy, and completing the pre-upgrade checklist.
+:keywords: upgrade, update, plan, checklist
 :navtitle: Upgrade {prod-short}
 :page-aliases: administration-guide:upgrading-che.adoc, installation-guide:upgrading-che.adoc, installation-guide:upgrading-che-known-issues.adoc, installation-guide:rolling-back-a-che-upgrade.adoc, installation-guide:upgrading-che-namespace-strategies-other-than-per-user.adoc, upgrading-che-namespace-strategies-other-than-per-user.adoc, upgrading-che-7-41-on-openshift.adoc
 
@@ -9,7 +9,31 @@
 = Upgrade {prod-short}
 
 [role="_abstract"]
-Keep your {prod-short} deployment current by upgrading to the latest version. Upgrading delivers bug fixes, security patches, and new capabilities to your developers with minimal disruption.
+Upgrade your {prod-short} deployment to the latest version to receive bug fixes, security patches, and new capabilities with minimal disruption.
 
-Before you upgrade, save and push all work in running workspaces, then stop all workspaces. The Operator handles the server component upgrade automatically. Workspaces resume normally after the upgrade completes.
+== How the upgrade works
+
+When you upgrade {prod-short}, the Operator handles the server component upgrade automatically. You do not need to manually update individual pods or configurations. The Operator:
+
+* Replaces the {prod-short} server, dashboard, gateway, and plug-in registry pods with the new version.
+* Upgrades the {devworkspace} Operator to the version bundled with the new release.
+* Preserves the existing `CheCluster` custom resource configuration.
+
+Running workspaces are not automatically restarted during the upgrade. Developers must stop their workspaces before the upgrade and restart them after the upgrade completes.
+
+== Supported upgrade path
+
+{prod-short} supports upgrading from the previous minor version to the current version.
+
+Direct upgrades that skip minor versions are not supported. If your deployment is more than one minor version behind, upgrade one minor version at a time.
+
+== Pre-upgrade checklist
+
+Complete the following steps before upgrading:
+
+. Review the release notes for breaking changes and new features.
+. Notify developers to save and push all uncommitted work in their running workspaces.
+. Stop all running workspaces. The upgrade does not automatically stop workspaces, and running workspaces might encounter errors during the upgrade.
+. Choose an update approval strategy. See xref:specifying-the-update-approval-strategy.adoc[].
+. If you plan to upgrade from the command line, update `{prod-cli}` to the latest version. See xref:upgrading-the-chectl-management-tool.adoc[].
 

modules/upgrade/pages/upgrading-the-chectl-management-tool.adoc

@@ -1,12 +1,10 @@
 :_content-type: PROCEDURE
-:description: Upgrading the chectl management tool
-:keywords: overview, upgrading, chectl, cli
+:description: Update the CLI management tool to the latest version before upgrading.
+:keywords: upgrade, chectl, cli, update
 :navtitle: Update the {prod-cli} management tool
 :page-aliases: administration-guide:upgrading-the-chectl-management-tool.adoc
 
 [id="upgrading-the-{prod-cli}-management-tool"]
-= Upgrading the {prod-cli} management tool
-
-include::partial$snip_persona-admin.adoc[]
+= Update the {prod-cli} management tool
 
 include::example$snip_{project-context}-upgrading-the-chectl-management-tool.adoc[]

modules/upgrade/partials/snip_installing-che-in-a-restricted-environment-additional-resources.adoc

@@ -1,5 +1,6 @@
 :_content-type: SNIPPET
 
+[role="_additional-resources"]
 .Additional resources
 
 * link:https://docs.openshift.com/container-platform/{ocp4-ver}/operators/understanding/olm-rh-catalogs.html[Red Hat-provided Operator catalogs]