Doc: FBC one step process documentation

docs/users/contributing-via-pr.md

@@ -4,14 +4,16 @@
 To submit an operator one has to do these steps
 
 1. Fork project based on desired [Operator Repository](./pipelines_overview.md#operator-repositories)
-1. Place the operator in the target directory. [More info](./contributing-where-to.md)
+2. Place the operator in the target directory. [More info](./contributing-where-to.md)
     - operators
-1. Configure `ci.yaml` file. [More info](./operator-ci-yaml.md)
+3. Configure `ci.yaml` file. [More info](./operator-ci-yaml.md)
     - Setup reviewers
     - Enable FBC mode
-1. Make a pull request with a new operator bundle or catalog changes
-1. Verify tests and fix problems, if possible
-1. Ask for help in the PR in case of problems
+    - Add template to catalog mapping
+4. Configure the `release-config.yaml` file if you want to automatically release the operator to the OCP catalogs. [More info](./fbc_autorelease.md#release-configyaml)
+5. Make a pull request with a new operator bundle or catalog changes
+6. Verify tests and fix problems, if possible
+7. Ask for help in the PR in case of problems
 
 
 ## Pull request

docs/users/contributing-where-to.md

@@ -15,6 +15,7 @@ Once you have forked the upstream repo, you will require to add your Operator Bu
 │       │   │   └── tools.opdev.io_demoresources.yaml
 │       │   ├── metadata
 │       │   │   └── annotations.yaml
+│       │   ├── release-config.yaml
 │       │   └── tests
 │       │       └── scorecard
 │       │           └── config.yaml

docs/users/fbc_autorelease.md

@@ -0,0 +1,70 @@
+# File-Based Catalog - auto-release
+By the nature of the File-Based Catalog (FBC) mode, the release of operator is made of two steps.
+
+* The first step builds, tests and releases bundle image
+* The second step adds a bundle to OCP catalog and releases it
+
+The second step can be now automated and user is no longer required to manually create a
+second PR with catalog changes. The release pipeline will take care of it.
+
+The process will require an additional configuration in the `release-config.yaml` file.
+Once a PR with new bundle and `release-config.yaml` is merged, the release pipeline will
+open a new PR with catalog changes.
+
+Example of such PR can be found [here](https://github.com/Allda/community-operators-pipeline-preprod/pull/20).
+The second PR is linked with it original PR and looks like [this](https://github.com/Allda/community-operators-pipeline-preprod/pull/25):
+
+![Release info](../img/fbc-auto-release-pr.png)
+
+## release-config.yaml
+
+If you want your operators to be automatically released to the OCP catalogs in the FBC mode,
+you will need to configure the `release-config.yaml` file. The file should be placed
+into the bundle version directory, e.g. `operators/aqua/0.0.2/release-config.yaml`.
+
+```
+tree operators/aqua
+.
+├── 0.0.2
+│   ├── release-config.yaml # This is the file
+│   ├── manifests
+│   └── metadata
+├── catalog-templates
+├── ci.yaml
+└── Makefile
+```
+Its content determines where exactly the bundle will be released in terms of
+the OCP version and the place in the update graph.
+
+### Example
+
+```yaml
+---
+catalog_templates:
+  - template_name: basic.yaml
+    channels: [my-channel]
+    replaces: aqua.0.0.1
+  - template_name: semver.yaml
+    channels: [Fast, Stable]
+```
+The example above shows a release configuration where operator bundle is going to be
+released to the `my-channel` channel in the `basic.yaml` catalog template and to the
+`Fast` and `Stable` channels in the `semver.yaml` catalog template.
+
+The `replaces` field is optional and it specifies the bundle that the new bundle
+replaces in the update graph.
+
+### File structure
+The schema of the file is available here: [release-config.yaml schema](https://github.com/redhat-openshift-ecosystem/operator-pipelines/blob/main/operator-pipeline-images/operatorcert/schemas/release-config-schema.json).
+The schema is validated automatically in the pipeline and the PR will fail with explanations if the file is not valid.
+
+Here is a summary of the file structure:
+
+* The top-level key is `catalog_templates` which is a list of objects.
+* Each object has the following keys:
+    * `template_name` - the name of the catalog template file in the `catalog-templates` directory.
+    * `channels` - a list of channels where the bundle should be released.
+        * In case of using `SemVer` a user can pick from allowed values: `Fast`, `Stable` and `Candidate`.
+    * `replaces` - the bundle that the new bundle replaces in the update graph. (**Optional**, only for the basic templates)
+    * `skips` - a list of bundles that should be skipped in the update graph. (**Optional**, only for the basic templates)
+    * `skipRange` - a range of bundles that should be skipped in the update graph. (**Optional**, only for the basic templates)

docs/users/fbc_workflow.md

@@ -18,13 +18,59 @@ File-based catalog templates serve as a simplified view of a catalog that can be
 by the user. The OPM currently supports 2 types of templates and it is up to the user which
 template the operator will be using.
 
-* Basic template
-* SemVer template
+* Basic template - `olm.template.basic`
+* SemVer template - `olm.semver`
 
 More information about each template can be found at [opm doc](https://olm.operatorframework.io/docs/reference/catalog-templates/).
 
 The recommended template from the maintainability point of view is `SemVer`.
 
+### FBC template mapping
+To be able to generate a catalog from templates a user needs to provide a mapping between
+template and catalog. The mapping is stored in the `ci.yaml` file. Based on your preference
+you can map a template to a catalog version with 1:N mapping or 1:1 mapping.
+
+Here is an example of the `ci.yaml` file with single template rendering multiple catalogs (`1:N`):
+
+```yaml
+---
+fbc:
+  enabled: true
+  catalog_mapping:
+    - template_name: my-custom-semver-template.yaml # The name of the file inside ./catalog-templates directory
+      catalogs_names: # a list of catalogs within the /catalogs directory
+        - "v4.15"
+        - "v4.16"
+        - "v4.17"
+      type: olm.semver
+    - template_name: my-custom-basic-template.yaml # The name of the file inside catalog-templates directory
+      catalogs_names:
+        - "v4.12"
+        - "v4.13"
+      type: olm.template.basic
+```
+
+And here is an example of the `ci.yaml` file with a single template rendering a single catalog (`1:1`):
+
+```yaml
+---
+fbc:
+  enabled: true
+  catalog_mapping:
+  - template_name: v4.14.yaml
+    catalog_names: ["v4.14"]
+    type: olm.template.basic
+  - template_name: v4.15.yaml
+    catalog_names: ["v4.15"]
+    type: olm.template.basic
+  - template_name: v4.16.yaml
+    catalog_names: ["v4.16"]
+    type: olm.template.basic
+  - template_name: v4.17.yaml
+    catalog_names: ["v4.17"]
+    type: olm.template.basic
+```
+
 ## Generate catalogs using templates
 To generate a final catalog for an operator a user needs to execute different `opm`
 commands based on the template type. We as operator pipeline maintainers want
@@ -43,6 +89,7 @@ The right place for the Makefile is in the operator's root directory
 ```
 .
 ├── 0.0.1
+|   ├── release-config.yaml
 │   ├── manifests
 │   └── metadata
 ├── catalog-templates
@@ -51,8 +98,6 @@ The right place for the Makefile is in the operator's root directory
 
 ```
 
-You can modify the Makefile based on your needs and use it to generate catalogs by running `make catalogs`.
-
 > [!IMPORTANT]
 > In case an operator isn't shipped to all OCP catalog versions manually update `OCP_VERSIONS`
 > variable in the `Makefile` and include only versions supported by an operator.
@@ -83,6 +128,15 @@ catalogs
 ```
 
 ### Adding new bundle to Catalog
+A new bundle can be added automatically to your templates and catalogs if you use
+the automated release feature. The process is described in the
+[fbc auto-release](./fbc_autorelease.md) documentation.
+
+It is **highly recommended to use the automated release feature** as it simplifies the process
+from the user perspective.
+
+However if you want to manually add a new bundle to the catalog follow the steps below.
+
 To add a bundle to the catalog you need to first submit the new version of the operator
 using traditional [PR workflow](./contributing-via-pr.md). The operator pipeline builds,
 tests, and releases the bundle into the registry. **At this point, the operator is not available

docs/users/operator-ci-yaml.md

@@ -45,12 +45,29 @@ The `fbc.version_promotion_strategy` option defines the strategy for promoting t
 - `always` - the operator will be promoted to the next OCP version automatically
 - `review-needed` - the operator will be promoted to the next OCP version automatically, but the PR will be created and the reviewers will be asked to review the changes
 
+### `fbc.catalog_mapping`
+The mapping serves as a link between catalog templates within the `./catalog-templates` directory and catalogs within the `./catalogs` directory.
+
+For more details and structure visit the [FBC workflow page](./fbc_workflow.md#fbc-template-mapping).
+
 ### Example
 ```yaml
 ---
 fbc:
-    enabled: true
-    version_promotion_strategy: never
+  enabled: true
+  version_promotion_strategy: never
+  catalog_mapping:
+    - template_name: my-custom-semver-template.yaml # The name of the file inside ./catalog-templates directory
+        catalogs_names: # a list of catalogs within the /catalogs directory
+          - "v4.15"
+          - "v4.16"
+          - "v4.17"
+        type: olm.semver
+    - template_name: my-custom-basic-template.yaml # The name of the file inside catalog-templates directory
+        catalogs_names:
+          - "v4.12"
+          - "v4.13"
+        type: olm.template.basic
 ```
 
 

docs/users/static_checks.md

@@ -52,15 +52,15 @@ The test is based on `operator-sdk bundle validate` command with `name=operatorh
 The test is based on `operator-sdk bundle validate` command with `suite=operatorframework` test suite [(link)](https://sdk.operatorframework.io/docs/cli/operator-sdk_bundle_validate/#operator-sdk-bundle-validate).
 
 #### check_required_fields
-| Field name | Validation | Description |
-|------------|------------|------|
-| `spec.displayName` | `.{3,50}` | A string with 3 - 50 characters |
-| `spec.description` | `.{20,}` | A bundle description with at least 20 characters |
-| `spec.icon` | `media` | A valid base64 content with a supported media type (`{"base64data": <b64 content>, "mediatype": enum["image/png", "image/jpeg", "image/gif", "image/svg+xml"]}`) |
-| `spec.version` | `SemVer` | Valid semantic version |
-| `spec.maintainers` |  | At least 1 maintainer contacts. Example: `{"name": "User 123", "email": "user@redhat.com"}` |
-| `spec.provider.name` | `.{3,}` | A string with at least 3 characters |
-| `spec.links` |  | At least 1 link. Example: `{"name": "Documentation", "url": "https://redhat.com"}` |
+| Field name           | Validation | Description                                                                                                                                                      |
+| -------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `spec.displayName`   | `.{3,50}`  | A string with 3 - 50 characters                                                                                                                                  |
+| `spec.description`   | `.{20,}`   | A bundle description with at least 20 characters                                                                                                                 |
+| `spec.icon`          | `media`    | A valid base64 content with a supported media type (`{"base64data": <b64 content>, "mediatype": enum["image/png", "image/jpeg", "image/gif", "image/svg+xml"]}`) |
+| `spec.version`       | `SemVer`   | Valid semantic version                                                                                                                                           |
+| `spec.maintainers`   |            | At least 1 maintainer contacts. Example: `{"name": "User 123", "email": "user@redhat.com"}`                                                                      |
+| `spec.provider.name` | `.{3,}`    | A string with at least 3 characters                                                                                                                              |
+| `spec.links`         |            | At least 1 link. Example: `{"name": "Documentation", "url": "https://redhat.com"}`                                                                               |
 
 #### check_dangling_bundles
 The test prevents from releasing an operator and keeping any previous bundle dangling.
@@ -133,6 +133,10 @@ This check will ensure that all bundle images in the file based catalog for give
 operator catalog(s) use allowed image registry. Allowed registries are configured
 in `(repo_root)/config.yaml` under the key `allowed_bundle_registries`.
 
+#### check_schema_bundle_release_config
+The test validates the `release-config.yaml` file against the schema. The schema
+the file including the schema is described [here](./fbc_autorelease.md#release-configyaml).
+
 ## Running tests locally
 
 ```bash

mkdocs.yml

@@ -17,8 +17,9 @@ nav:
       - "Before submitting your Operator": "users/contributing-prerequisites.md"
       - "Where to place operator": "users/contributing-where-to.md"
       - "Best practices": "users/best-practices.md"
-      - "File base catalog onboarding": "users/fbc_onboarding.md"
-      - "File base catalog workflow": "users/fbc_workflow.md"
+      - "File based catalog onboarding": "users/fbc_onboarding.md"
+      - "File based catalog workflow": "users/fbc_workflow.md"
+      - "File based catalog auto-release": "users/fbc_autorelease.md"
       - "OKD/OpenShift Catalogs criteria and options": "users/packaging-required-criteria-ocp.md"
   - "Admin":
       - "Admin guide": "pipeline-admin-guide.md"