update the formulary to reflect the new schema for basic catalog templates

Signed-off-by: Jordan Keister <[email protected]>

Author: grokspawn

content/en/docs/advanced-tasks/catalog-update-formulary.md

@@ -8,34 +8,12 @@ weight: 5
 [File-based-catalogs][file-based-catalog-spec] (FBC) and [catalog templates][templates-doc] (templates)  provide operator authors with standardized schemas to express operator upgrade graphs.  However, without explicit tooling users require clear examples of how to achieve routine goals.  This document is an attempt to establish a formulary of common operations, specifically with the intention of making these pieces automatable.  This is in no way an exhaustive list.
 
 ## Conventions
-Formulae will be identified as pertaining to either FBC or [semver catalog template][semver-template-doc] (semver template).  Since FBC and the [basic catalog template][basic-template-doc] (basic template) both represent the upgrade graph in the set of `olm.channel` objects, instructions for FBC will also be applicable to the `basic template`. Manipulations of `olm.bundle` attributes are limited to FBC representation only. 
+Formulae will be identified as FBC, [basic catalog template][basic-template-doc] (basic template), or [semver catalog template][semver-template-doc] (semver template).
 Schema manipulations will be modeled using YAML and [yq][yq].  Wherever possible, example input will be limited to the relevant object hierarchies.  Truncation is indicated by elipses (...) before and after the text.
 
-
 ## Examples
 For brevity, all formulae will refer to the same example, for semver template and FBC.  For convenience, all semver bundle image pullspecs will express versions which match the bundle version (instead of SHAs). 
 
-### semver template example
-Formulae presume the following content is saved to the file `semver.yaml`
-```yaml
-schema: olm.semver
-generateMajorChannels: false
-generateMinorChannels: true
-candidate:
-  bundles:
-  - image: quay.io/organization/testoperator:v1.0.0
-  - image: quay.io/organization/testoperator:v1.0.1
-  - image: quay.io/organization/testoperator:v1.1.0
-fast:
-  bundles:
-  - image: quay.io/organization/testoperator:v1.0.1
-  - image: quay.io/organization/testoperator:v1.1.0
-stable:
-  bundles:
-  - image: quay.io/organization/testoperator:v1.0.1
-  ```
-
-
 ### FBC example
 Formulae presume the following content is saved to the file `fbc.yaml`
 
@@ -84,28 +62,54 @@ schema: olm.channel
 ```
 
 
-## Formulae
-
-### Adding a new bundle to an existing channel
-#### semver
-Add a new `testoperatorv1.1.1` bundle pullspec to the `Candidate` channel archetype
-
-```bash
-yq eval '.candidate.bundles += [{"image" : "quay.io/organization/testoperator:v1.1.1"}]' semver.yaml
+### basic template example
+Formulae presume the following context is saved to the file `basic.yaml`
+```yaml
+schema: olm.template.basic
+entries:
+  - schema: olm.package
+    name: testoperator
+    defaultChannel: stable
+  - schema: olm.channel
+    package: testoperator
+    name: stable
+    entries:
+      - name: testoperator.v0.1.0
+      - name: testoperator.v0.2.0
+        replaces: testoperator.v0.1.0
+  - schema: olm.bundle
+    image: quay.io/organization/testoperator:v0.1.0
+  - schema: olm.bundle
+    image: quay.io/organization/testoperator:v0.2.0
 ```
 
-produces updated `Candidate` archetype contents:
-
+### semver template example
+Formulae presume the following content is saved to the file `semver.yaml`
 ```yaml
-...
+schema: olm.semver
+generateMajorChannels: false
+generateMinorChannels: true
 candidate:
   bundles:
   - image: quay.io/organization/testoperator:v1.0.0
   - image: quay.io/organization/testoperator:v1.0.1
   - image: quay.io/organization/testoperator:v1.1.0
-  - image: quay.io/organization/testoperator:v1.1.1
-...
-```
+fast:
+  bundles:
+  - image: quay.io/organization/testoperator:v1.0.1
+  - image: quay.io/organization/testoperator:v1.1.0
+stable:
+  bundles:
+  - image: quay.io/organization/testoperator:v1.0.1
+  ```
+
+
+
+
+
+## Formulae
+
+### Adding a new bundle to an existing channel
 
 #### FBC
 Add a new `testoperator.v1.1.1` edge to an existing `candidate-v1.1` channel
@@ -129,19 +133,65 @@ package: testoperator
 schema: olm.channel
 ...
 ```
-{{% alert title="Warning" color="warning" %}}
-This example illustrates how it is possible to inadvertently create multiple channel heads
-{{% /alert %}}
-`opm validate` result for this output would be:
+> [!CAUTION]
+> This example illustrates how it is possible to inadvertently create multiple channel heads
+>
+> `opm validate` result for this output would be:
+> 
+> ```bash
+> FATA[0000] invalid index:
+> └── invalid package "testoperator":
+>     └── invalid channel "candidate-v1.1":
+>         ├── multiple channel heads found in graph: testoperator.v1.1.0, testoperator.v1.1.1
+> ```
+
+#### basic
+Add a new `testoperator.v0.2.1` bundle pullspec to the existing `stable` channel
+
+```bash
+yq eval 'select(.schema == "olm.template.basic").entries[] |= select(.schema == "olm.channel" and .name == "stable").entries += [{"name" : "testoperator.v0.2.1", "replaces": "testoperator.v0.2.0"}]' basic.yaml
+```
+
+produces updated `stable` channel:
+
+```yaml
+...
+  - schema: olm.channel
+    package: testoperator
+    name: stable
+    entries:
+      - name: testoperator.v0.1.0
+      - name: testoperator.v0.2.0
+        replaces: testoperator.v0.1.0
+      - name: testoperator.v0.2.1
+        replaces: testoperator.v0.2.0
+...
+```
+
+#### semver
+Add a new `testoperator.v1.1.1` bundle pullspec to the `Candidate` channel archetype
 
 ```bash
-FATA[0000] invalid index:
-└── invalid package "testoperator":
-    └── invalid channel "candidate-v1.1":
-        ├── multiple channel heads found in graph: testoperator.v1.1.0, testoperator.v1.1.1
+yq eval '.candidate.bundles += [{"image" : "quay.io/organization/testoperator:v1.1.1"}]' semver.yaml
+```
+
+produces updated `Candidate` archetype contents:
+
+```yaml
+...
+candidate:
+  bundles:
+  - image: quay.io/organization/testoperator:v1.0.0
+  - image: quay.io/organization/testoperator:v1.0.1
+  - image: quay.io/organization/testoperator:v1.1.0
+  - image: quay.io/organization/testoperator:v1.1.1
+...
 ```
 
+
 ### Adding a new 'replaces' link between two existing bundles
+> [!NOTE] 
+> This operation is not possible for the semver template, which exclusively leverages semver ordering to generate an opinonated upgrade graph.
 
 #### FBC
 Adding a new `testoperator.v1.1.1` bundle version edge with a replaces link to its predecessor `testoperator.v1.1.0` version which already exists in the channel. 
@@ -166,8 +216,33 @@ schema: olm.channel
 ...
 ```
 
+#### basic
+Adding a new `testoperator.v0.1.1` bundle version edge with a replaces link to its predecessor `testoperator.v0.1.0` version which already exists in the channel.
+
+```bash
+yq eval 'select(.schema == "olm.template.basic").entries[] |= select(.schema == "olm.channel" and .name == "stable").entries += [{"name" : "testoperator:v0.1.1", "replaces": "testoperator:v0.1.0"}]' basic.yaml
+```
+
+produces updated `stable` channel:
+
+```yaml
+...
+  - schema: olm.channel
+    package: testoperator
+    name: stable
+    entries:
+      - name: testoperator.v0.1.0
+      - name: testoperator.v0.2.0
+        replaces: testoperator.v0.1.0
+      - name: testoperator:v0.1.1
+        replaces: testoperator:v0.1.0
+...
+```
+
 
 ### Removing a specific bundle version
+> [!NOTE] 
+> This operation is not possible for the semver template, which exclusively leverages semver ordering to generate an opinonated upgrade graph.
 
 #### FBC
 Remove the upgrade edge from the example `candidate-v1.1` channel which refers to bundle version `testoperator.v1.1.0`. 
@@ -190,34 +265,27 @@ schema: olm.channel
 Please note that removing the only edge for a channel as in this example will yield an explicitly empty array.  This will produce an error in `opm validate`. 
 {{% /alert %}}
 
-### Substituting a bundle version in the upgrade graph
-
-#### semver
-For all channels, replace instances of `quay.io/organization/testoperator:v1.1.0` with `quay.io/organization/testoperator:v1.1.0-CVE`
+#### basic
+Remove the upgrade edge from the example `stable` channel which refers to bundle version `testoperator.v0.2.0`.
 
 ```bash
-yq '(..| select(has("image") and .image == "quay.io/organization/testoperator:v1.1.0")).image = "quay.io/organization/testoperator:v1.1.0-cve"' semver.yaml
+yq eval 'select(.schema == "olm.template.basic").entries[] |= del(select(.schema == "olm.channel" and .name == "stable").entries[]| select(.name == "testoperator.v0.2.0"))' basic.yaml
 ```
-produces updated template:
+
+produces updated `stable` channel:
 
 ```yaml
-schema: olm.semver
-generatemajorchannels: false
-generateminorchannels: true
-candidate:
-  bundles:
-    - image: quay.io/organization/testoperator:v1.0.0
-    - image: quay.io/organization/testoperator:v1.0.1
-    - image: quay.io/organization/testoperator:v1.1.0-cve
-fast:
-  bundles:
-    - image: quay.io/organization/testoperator:v1.0.1
-    - image: quay.io/organization/testoperator:v1.1.0-cve
-stable:
-  bundles:
-    - image: quay.io/organization/testoperator:v1.0.1
+...
+  - schema: olm.channel
+    package: testoperator
+    name: stable
+    entries:
+      - name: testoperator.v0.1.0
+...
 ```
 
+### Substituting a bundle version in the upgrade graph
+
 #### FBC
 For all graph edges, replaces instances of `testoperator.v1.1.0` with a different bundle version `testoperator.v1.1.0-CVE`
 
@@ -271,7 +339,59 @@ package: testoperator
 schema: olm.channel
 ```
 
+#### basic
+For all channels, replace instances of `testoperator:v0.1.0` with `testoperator:v0.1.0-CVE`
+
+```bash
+yq '(..| select(. == "testoperator.v0.1.0")) |="testoperator.v0.1.0-CVE"' basic.yaml
+```
+
+produces updated channels:
+
+```yaml
+...
+  - schema: olm.channel
+    package: testoperator
+    name: stable
+    entries:
+      - name: testoperator.v0.1.0-CVE
+      - name: testoperator.v0.2.0
+        replaces: testoperator.v0.1.0-CVE
+...
+```
+
+#### semver
+For all channels, replace instances of `quay.io/organization/testoperator:v1.1.0` with `quay.io/organization/testoperator:v1.1.0-CVE`
+
+```bash
+yq '(..| select(has("image") and .image == "quay.io/organization/testoperator:v1.1.0")).image = "quay.io/organization/testoperator:v1.1.0-cve"' semver.yaml
+```
+produces updated template:
+
+```yaml
+schema: olm.semver
+generatemajorchannels: false
+generateminorchannels: true
+candidate:
+  bundles:
+    - image: quay.io/organization/testoperator:v1.0.0
+    - image: quay.io/organization/testoperator:v1.0.1
+    - image: quay.io/organization/testoperator:v1.1.0-cve
+fast:
+  bundles:
+    - image: quay.io/organization/testoperator:v1.0.1
+    - image: quay.io/organization/testoperator:v1.1.0-cve
+stable:
+  bundles:
+    - image: quay.io/organization/testoperator:v1.0.1
+```
+
+
+
 ### Introducing a new replacement relationship in the upgrade graph
+> [!NOTE] 
+> This operation is not possible for the semver template, which exclusively leverages semver ordering to generate an opinonated upgrade graph.
+
 #### FBC
 Substitute an existing 'replaces' link target for `testoperator.v1.1.0` with a different bundle version `testoperator.v1.0.0`.
 
@@ -292,6 +412,24 @@ schema: olm.channel
 ...
 ```
 
+#### basic
+Substitute an existing 'replaces' link target for `testoperator.v0.2.0` with a different bundle version `testoperator.v0.1.5`.
+
+```bash
+yq eval '.entries[] |= select(.schema == "olm.channel" and .name == "stable").entries |= [{"name" : "testoperator:v0.2.0", "replaces": "testoperator:v0.1.5"}]' basic.yaml
+```
+produces updated `stable` channel:
+
+```yaml
+...
+  - schema: olm.channel
+    package: testoperator
+    name: stable
+    entries:
+      - name: testoperator:v0.2.0
+        replaces: testoperator:v0.1.5
+...
+```