doc: release workflow

docs/design/assets/release.uml

@@ -0,0 +1,72 @@
+@startuml
+'NOTE: use http://sujoyu.github.io/plantuml-previewer to render the Sequence diagram
+
+title Release Workflow for 1.2.3 release
+
+autonumber
+actor "Release\n Manager" as RM order 10
+actor Reviewer order 20
+database Upstream order 30
+control CI order 40
+participant Publish order 50
+database Quay order 60
+
+activate RM
+RM -> RM: make initiate-release
+RM -> Upstream: open PR ""chore(release): 1.2.3"" \n against ""main"" branch
+deactivate RM
+
+activate Upstream
+Upstream -> CI: run checks, e2e
+CI -[#green]> Upstream:  pass
+deactivate Upstream
+
+Reviewer -> Upstream: approve &\n merge to main branch
+
+== candidate release prep ==
+activate CI
+Upstream -> CI: release workflow (release.yaml)
+CI -> CI: run e2e
+CI -> CI: generate release notes
+CI -> CI: create GH release notes
+CI -> Upstream: git tag ""v1.2.3"" and \ngit push tag ""v1.2.3""
+CI -> Upstream: publish pre-release to GH
+deactivate CI
+== candidate release prep ==
+
+== candidate release  ==
+Upstream -> CI: start candidate release (olm-candidate.yaml)
+CI -> Publish: candidate release (olm-publish.yaml)
+CI -> Publish: run olm-publish (channels: development, candidate)
+    activate Publish #FFBBBB
+    Publish -> Publish: login to quay
+    Publish -> Publish: merge olm-catalog branch
+    Publish -> Publish: build operator image
+    Publish -[#red]> Quay: push operator image
+    Publish -> Publish: build bundle image
+    Publish -[#red]> Quay: push bundle image
+    Publish -> Publish: make catalog-image
+
+        activate Publish #lightcoral
+        Publish -> Publish: opm render <bundle-image> to olm/observability-operator-index/index.yaml
+        Publish -> Publish: olm/update-channels.sh <CHANNELS> <operator-bundle>
+        deactivate Publish
+    Publish -> Publish: git commit changes to bundle and olm dir
+    Publish -[#red]> Quay: publish catalog-image
+    Publish -> Upstream:  push catalog changes to olm-catalog branch
+    deactivate Publish
+== candidate release  ==
+
+== stable release  ==
+RM -> Upstream: remove draft from release
+Upstream -> CI: stable release (olm-stable.yaml)
+CI -> Publish: run olm-publish (channels: development, candidate, stable)
+    activate Publish #DarkSalmon
+    Publish -> Publish: olm-publish workflow
+    ...same release worflow...
+    Publish -> Quay: publish catalog-image
+    Publish -> Upstream:  push catalog changes to olm-catalog branch
+    deactivate Publish
+== stable release  ==
+
+@enduml

docs/design/release.md

@@ -0,0 +1,14 @@
+# Release Worflow
+
+## Important pointers
+
+* `olm-catalog` branch is the "release" branch
+* Due to the nature of File Based Catalogs, the catalog's [index](https://github.com/rhobs/observability-operator/blob/olm-catalog/olm/observability-operator-index/index.yaml) file
+  is stored under  [`olm-catalog` branch](https://github.com/rhobs/observability-operator/tree/olm-catalog)
+* `update-channels.sh` script is kept under the [olm directory](https://github.com/rhobs/observability-operator/blob/olm-catalog/olm/update-channels.sh)
+
+## Release Workflow
+
+![Release Workflow](./assets/release.png)
+
+NOTE: the source for the UML can be found under [assets directory](./assets/release.uml)