Draft documentation for initial upgrade support

Signed-off-by: Mikalai Radchuk <mradchuk@redhat.com>

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 in OLM 1.0 is incomplete: only `replaces` directive is taken into account.
+
+Kubernetes 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.
+
+**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 case for upgrades within the major version zero:
+
+* It is not possible to automatically upgrade one patch versions to another when both major and minor versions are `0`. Meaning 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, using this option 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 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.