From 9ecac9725fe668949da937886c3cbb7d214dbcf6 Mon Sep 17 00:00:00 2001
From: Mikalai Radchuk <mradchuk@redhat.com>
Date: Thu, 14 Nov 2024 11:49:32 +0100
Subject: [PATCH] Fix docs: "How to" section

There were several intentional breaking changes in the API
which are now included in v0.18.0 release.

This commit mostly focuses on updating the documentation to
reflect API changes. This includes making sure that snippets
and example outputs match the current state of the project.

Relevant PRs:
* https://github.com/operator-framework/operator-controller/pull/1439
* https://github.com/operator-framework/operator-controller/pull/1434

Signed-off-by: Mikalai Radchuk <mradchuk@redhat.com>
---
 docs/howto/how-to-channel-based-upgrades.md | 20 ++++++++++----------
 docs/howto/how-to-pin-version.md            |  7 +++----
 docs/howto/how-to-version-range-upgrades.md |  7 +++----
 docs/howto/how-to-z-stream-upgrades.md      |  9 ++++-----
 4 files changed, 20 insertions(+), 23 deletions(-)

diff --git a/docs/howto/how-to-channel-based-upgrades.md b/docs/howto/how-to-channel-based-upgrades.md
index e7638d1a1..f401548fc 100644
--- a/docs/howto/how-to-channel-based-upgrades.md
+++ b/docs/howto/how-to-channel-based-upgrades.md
@@ -10,19 +10,18 @@ kind: ClusterExtension
 metadata:
   name: argocd
 spec:
+  namespace: argocd
+  serviceAccount:
+    name: argocd-installer
   source:
     sourceType: Catalog
     catalog:
       packageName: argocd-operator
       # Automatically upgrade to the latest version found in the preview and dev-preview channels
       channels: [dev-preview, preview]
-  install:
-    namespace: argocd
-    serviceAccount:
-      name: argocd-installer
 ```
 
-Note that the `version` field also accepts a version range to further restrict the set of possible upgradable operator versions.
+Note that the `version` field also supports [version pinning](./how-to-pin-version.md) and [version ranges](./how-to-version-range-upgrades.md) to further restrict the set of possible upgradable operator versions.
 
 Example:
 
@@ -32,14 +31,15 @@ kind: ClusterExtension
 metadata:
   name: argocd
 spec:
+  namespace: argocd
+  serviceAccount:
+    name: argocd-installer
   source:
     sourceType: Catalog
     catalog:
       packageName: argocd-operator
       channels: [stable] # Automatically upgrade to the latest version found in ‘stable’
-      version: “!1.3.2” # Don’t allow version 1.3.2
-  install:
-    namespace: argocd
-    serviceAccount:
-      name: argocd-installer
+      version: "!=1.3.2" # Don’t allow version 1.3.2
 ```
+
+For more information on SemVer version ranges see [version ranges](../concepts/version-ranges.md)
diff --git a/docs/howto/how-to-pin-version.md b/docs/howto/how-to-pin-version.md
index 5dc0660b0..6072582f4 100644
--- a/docs/howto/how-to-pin-version.md
+++ b/docs/howto/how-to-pin-version.md
@@ -10,15 +10,14 @@ kind: ClusterExtension
 metadata:
   name: argocd
 spec:
+  namespace: argocd
+  serviceAccount:
+    name: argocd-installer
   source:
     sourceType: Catalog
     catalog:
         packageName: argocd-operator
         version: 0.6.0 # Pin argocd-operator to v0.6.0
-  install:
-    namespace: argocd
-    serviceAccount:
-      name: argocd-installer
 ```
 
 For more information on SemVer version ranges see [version ranges](../concepts/version-ranges.md)
diff --git a/docs/howto/how-to-version-range-upgrades.md b/docs/howto/how-to-version-range-upgrades.md
index 1a502a2e2..58a2161b6 100644
--- a/docs/howto/how-to-version-range-upgrades.md
+++ b/docs/howto/how-to-version-range-upgrades.md
@@ -10,15 +10,14 @@ kind: ClusterExtension
 metadata:
   name: argocd
 spec:
+  namespace: argocd
+  serviceAccount:
+    name: argocd-installer
   source:
     sourceType: Catalog
     catalog:
       packageName: argocd-operator
       version: ">=3.0, <3.6"  # Install versions from v3.0.0 up to, but not including, v3.6.0
-  install:
-    namespace: argocd
-    serviceAccount:
-      name: argocd-installer
 ```
 
 For more information on SemVer version ranges see [version-ranges](../concepts/version-ranges.md)
diff --git a/docs/howto/how-to-z-stream-upgrades.md b/docs/howto/how-to-z-stream-upgrades.md
index 1a638fd1b..6ba440d2f 100644
--- a/docs/howto/how-to-z-stream-upgrades.md
+++ b/docs/howto/how-to-z-stream-upgrades.md
@@ -10,15 +10,14 @@ kind: ClusterExtension
 metadata:
   name: argocd
 spec:
+  namespace: argocd
+  serviceAccount:
+    name: argocd-installer
   source:
     sourceType: Catalog
     catalog:
       packageName: argocd-operator
-      version: “~2.3" # Automatically upgrade patch releases for v2.3
-  install:
-    namespace: argocd
-    serviceAccount:
-      name: argocd-installer
+      version: "~2.3" # Automatically upgrade patch releases for v2.3
 ```
 
 For more information on SemVer version ranges see [version ranges](../concepts/version-ranges.md)