Draft documentation for initial upgrade support

Signed-off-by: Mikalai Radchuk <[email protected]>

Author: Mikalai Radchuk

docs/drafts/initial-upgrade-support.md

@@ -0,0 +1,43 @@
+# Initial upgrade support
+
+This document explains how OLM 1.0 handles upgrades.
+
+OLM 1.0 introduces initial upgrade support with simplified UX for package authors and package admins which allows defining upgrade edges implicitly via [Semantic Versioning](https://semver.org/) standard.
+
+It also introduces an API to enable independently verified upgrades and downgrades.
+
+## Upgrade constraint semantics
+
+OLM 1.0 at the moment supports two upgrade constraint semantics:
+
+* [Semantic Versioning](https://semver.org/) (Semver)
+* [Legacy OLM 0 semantics](https://olm.operatorframework.io/docs/concepts/olm-architecture/operator-catalog/creating-an-update-graph/#methods-for-specifying-updates)
+
+**Note:** At the moment of writing legacy semantics support is incomplete: only `replaces` directive is supported.
+
+Manifests provided in this repo enable Semver support by default, but cluster admins can control which semantics to use by passing one of the arguments into `manager` binary:
+* `--feature-gates=ForceSemverUpgradeConstraints=true` - enable Semver
+* `--feature-gates=ForceSemverUpgradeConstraints=false` - disable Semver, use legacy semantics
+
+## Upgrades
+
+OLM Semver support provides simplified way for package authors to define compatible upgrades. As per Semver anything within major version (e.g. `>=1.0.0 <2.0.0`) is meant to be compatible. This means that package authors can simply publish a new package version following Semver specification and OLM will assume compatibility. There is no need for authors to explicitly define upgrade edges in the catalog anymore.
+
+**Note:** There is currently no support for automatic upgrades to a next major version. For now such upgrades will have to be independently verified and manually preformed (more on this below).
+
+### Upgrades within the major version zero
+
+As per Semver major version zero is for initial development and anything may change at any time. Given that there are some special rules for upgrades within the major version zero:
+
+* It is not possible to automatically upgrade a one patch versions to another when both major and minor versions are `0`. E.g. no automatic upgrades withing range `>= 0.0.1 <0.1.0`.
+* It is not possible to automatically upgrade from one minor version to another minor version within the major version zero. E.g. no upgrades from `0.1.0` to `0.2.0`. But one can upgrade from patch to patch version. E.g. upgrades are possible in ranges `>= 0.1.0 <0.2.0`, `>= 0.2.0 <0.3.0`, `>= 0.3.0 <0.4.0` and so on.
+
+To perform an upgrade in the cases mentioned above - the upgrade must be independently verified.
+
+## Independently verified upgrades and downgrades
+
+**Warning:** This option requires thorough manual verification of the desired operation prior to applying to production workloads. Depending on the package, it might lead to catastrophic consequences such as data loss.
+
+In cases when package admins need to upgrade or downgrade to a version which is not guaranteed to be compatible by Semver they can choose to set `.spec.upgradeConstraintPolicy` to `Ignore` on the relevant `Operator` resource.
+
+This option means that no upgrade constraints will be set on the package and version can be changed to any version available in catalogs for a given package.