Merge pull request #107 from wallrj/update-release-process-docs

Update the release process documentation

README.md

@@ -27,46 +27,40 @@ OLM will then install the newest cert-manager bundle in that release channel and
 
 ## Release Process
 
-In order to test that OLM can upgrade to the new version you can perform a test release,
-and publish a "release candidate" bundle by creating release candidate PRs to
-[Kubernetes Community Operators Repository][] and to
-[OpenShift Community Operators Repository][].
-
-Once these bundles have been merged, the release candidate version of cert-manager should be available
-in the "candidates" channel __only__.
-
-You can test upgrading to the new version by creating a Subscription targeting the "candidate" channel
-(which should also contain the latest stable version),
-and set the "startingCSV" to the last stable version
-and "installPlanApproval" to "Manual". E.g.
-
-```yaml
-apiVersion: operators.coreos.com/v1alpha1
-kind: Subscription
-metadata:
-  name: cert-manager
-  namespace: openshift-operators
-spec:
-  channel: candidate
-  installPlanApproval: Manual
-  name: cert-manager
-  source: community-operators
-  sourceNamespace: openshift-marketplace
-  startingCSV: cert-manager.v1.6.1
-```
-
-Then when you have published the release candidate, you should verify that you can upgrade cert-manager to the new version.
-Check the logs and events for upgrade errors during the upgrade.
+For each release, we first publish one or more release candidates on
+[Kubernetes Community Operators Repository][] and
+[OpenShift Community Operators Repository][],
+in the "candidate" [channel](https://olm.operatorframework.io/docs/best-practices/channel-naming/).
+
+This allows us to discover whether our latest "bundle" sources will pass RedHat's conformance scripts,
+which are automatically run in those two repositories.
+And it allows us test precisely the catalog entry that is generated by RedHat's release scripts,
+which are automatically run when PRs are merged in those two repositories.
+
+> ℹ️ Why? It may seem long-winded, but before I started doing this, there were
+> occasions when I didn't find bugs in the new version until after I'd published
+> the broken packages to the community-operators catalog, despite my best local
+> testing efforts with Kind + OLM + locally generated Catalog and Bundle images.
+> And I never found a way to test a locally generated Catalog with a CRC OpenShift cluster.
+>
+> This RC process allows me to start CRC OpenShift and test the release
+> candidate in the official RedHat catalogs.
 
 ### Release Steps
 
-* Add the new version to `CERT_MANAGER_VERSION` at the top of the `Makefile`
-* If this is a release candidate:
-  * Add `-rc1` as a suffix to `BUNDLE_VERSION`
-* If this is the final release:
+* Update `CERT_MANAGER_VERSION` at the top of the `Makefile`
+* (release candidate only)
+  * Add `-rc1` suffix to `BUNDLE_VERSION`
+  * Set `BUNDLE_CHANNELS ?= candidate`
+* (final release only )
   * Remove the `-rc1` suffix from `BUNDLE_VERSION`
-* Run `make bundle-build bundle-push catalog-build catalog-push` to generate a bundle and a catalog.
+  * Set `BUNDLE_CHANNELS ?= candidate stable`
+* Run `make bundle-generate`
+  * Inspect the changes
+  * *pause to investigate if there are unexpected changes
 * Run `make bundle-validate` to check the generated bundle files.
+  * Inspect warnings
+  * Consider whether the warnings can be easily fixed and if so fix them.
 * `git commit` the bundle changes.
 * [Preview the generated clusterserviceversion file on OperatorHub ](https://operatorhub.io/preview)
 * Test the generated bundle locally (See testing below)
@@ -82,6 +76,8 @@ Check the logs and events for upgrade errors during the upgrade.
 
   `make update-community-operators-prod`
 
+* Test the new release on the latest stable OpenShift (See [Testing on OpenShift][#testing-on-openshift]).
+
 [Kubernetes Community Operators Repository]: https://github.com/k8s-operatorhub/community-operators
 [OpenShift Community Operators Repository]: https://github.com/redhat-openshift-ecosystem/community-operators-prod
 [Where to contribute]: https://operator-framework.github.io/community-operators/contributing-where-to/