From 76a1ac1a9faf51ad9dacf3b5cfe0056f917c5802 Mon Sep 17 00:00:00 2001 From: Michael Ryan Peter Date: Thu, 16 Nov 2023 14:59:05 -0500 Subject: [PATCH 1/3] Issue #407: Docs for version range support Add docs explaining version range. Signed-off-by: Michael Ryan Peter --- docs/drafts/version-ranges.md | 49 +++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 docs/drafts/version-ranges.md diff --git a/docs/drafts/version-ranges.md b/docs/drafts/version-ranges.md new file mode 100644 index 000000000..ec03a0a98 --- /dev/null +++ b/docs/drafts/version-ranges.md @@ -0,0 +1,49 @@ +# Operator version ranges + +This document explains how to specify a version range to install or update an Operator with OLM 1.0. + +You define an Operator's target version in its custom resource (CR) file. +The following list describes how OLM resolves an Operator's target version, and the resulting actions: + +Not specifying a version in the CR +: Installs or updates the latest version of the Operator. +Updates are applied automatically when they are published to the catalog. + +Specifying a version in the CR +: Installs or updates the specified version. +Updates are not applied automatically. +If you want to update the Operator, you must manually edit the CR and apply the changes to the cluster. + +Specifying a channel +: Installs or updates the latest version of the Operator in the channel. +Updates are applied automatically when they are published to the specified channel. + +Specifying a version range in the CR +: Installs or updates the latest version of the Operator within the version range. +Updates that are within the specified range are automatically installed. +Updates that are outside of the specified range are not installed. + +The `spec.version` field uses the Masterminds `semver` package to enable the version range functionality. + +OLM 1.0 does not support following methods for specifying a version range: + +* Using tags and labels are not supported. +You must use semantic versioning to define a version range. +* Using [hypen range comparisons](https://github.com/Masterminds/semver#hyphen-range-comparisons) are not supported. +For example, the following range option is not supported: + + ```yaml + version: 3.0 - 3.6 + ``` + + To specify a range option, use a method similar to the following example: + + ```yaml + version: >=3.0 <3.6 + ``` + +You can use the `x`, `X`, and `*` characters as wildcard characters in all comparison operations. + +For more information about parsing, sorting, checking, and comparing version constraints, see the [Masterminds SemVer README](https://github.com/Masterminds/semver#semver). + +## Example CRs that specify a version range From a112f0fb4bc65768b67a08f0899b0a0dbe46b56f Mon Sep 17 00:00:00 2001 From: Michael Ryan Peter Date: Mon, 20 Nov 2023 15:05:21 -0500 Subject: [PATCH 2/3] Address feedback. Define operators and comparisons. - Remove references to the Mastermind SemVer docs - Define operators and comparisons - Address review feedback Signed-off-by: Michael Ryan Peter --- docs/drafts/version-ranges.md | 98 +++++++++++++++++++++++++---------- 1 file changed, 71 insertions(+), 27 deletions(-) diff --git a/docs/drafts/version-ranges.md b/docs/drafts/version-ranges.md index ec03a0a98..bd7013ad4 100644 --- a/docs/drafts/version-ranges.md +++ b/docs/drafts/version-ranges.md @@ -2,48 +2,92 @@ This document explains how to specify a version range to install or update an Operator with OLM 1.0. -You define an Operator's target version in its custom resource (CR) file. -The following list describes how OLM resolves an Operator's target version, and the resulting actions: +You define a version range in an Operator's custom resource (CR) file. -Not specifying a version in the CR -: Installs or updates the latest version of the Operator. -Updates are applied automatically when they are published to the catalog. +## Specifying a version range in the CR -Specifying a version in the CR -: Installs or updates the specified version. -Updates are not applied automatically. -If you want to update the Operator, you must manually edit the CR and apply the changes to the cluster. +If you specify a version range in the Operator's CR, OLM 1.0 installs or updates the latest version of the Operator that can be resolved within the version range. +The resolved version is the latest version of the Operator that satisfies the dependencies and constraints of the Operator and the environment. +Operator updates within the specified range are automatically installed if they can be resolved successfully. +Updates are not installed if they are outside of the specified range or if they cannot be resolved successfully. -Specifying a channel -: Installs or updates the latest version of the Operator in the channel. -Updates are applied automatically when they are published to the specified channel. +For more information about dependency and constraint resolution in OLM 1.0, see the [Deppy introduction](https://github.com/operator-framework/deppy#introductionhttps://github.com/operator-framework/deppy#introductionhttps://github.com/operator-framework/deppy#introduction) -Specifying a version range in the CR -: Installs or updates the latest version of the Operator within the version range. -Updates that are within the specified range are automatically installed. -Updates that are outside of the specified range are not installed. +### Comparisons -The `spec.version` field uses the Masterminds `semver` package to enable the version range functionality. +You define a version range by adding a comparison string to the `spec.version` field. A comparison string is composed of a list of comma or space separated values and one or more comparison operators. You can add an additional comparison string by including an OR (`||`) operator between the strings. -OLM 1.0 does not support following methods for specifying a version range: +#### Basic comparisons -* Using tags and labels are not supported. -You must use semantic versioning to define a version range. -* Using [hypen range comparisons](https://github.com/Masterminds/semver#hyphen-range-comparisons) are not supported. +| Operator | Definition | +|----------|-----------------------------------| +| `=` | equal (not aliased to an operator | +| `!=` | not equal | +| `>` | greater than | +| `<` | less than | +| `>=` | greater than or equal to | +| `<=` | less than or equal to | + +#### Range comparisons + +OLM 1.0 does not support hypen range comparisons. For example, the following range option is not supported: ```yaml version: 3.0 - 3.6 ``` - To specify a range option, use a method similar to the following example: +To specify a version range, use a method similar to the following example: - ```yaml - version: >=3.0 <3.6 - ``` +```yaml +version: >=3.0, <3.6 +``` + +#### Wildcards in comparisons You can use the `x`, `X`, and `*` characters as wildcard characters in all comparison operations. +If you use a wildcard character with the `=` operator, you define a patch level comparision. +This is equivalent to making a tilde range comparison. + +*Example comparisons with wildcard characters* +| Comparison | Equivalent | +|------------|---------------------| +| `1.2.x` | `>= 1.2.0, < 1.3.0` | +| `>= 1.2.x` | `>= 1.2.0` | +| `<= 2.x` | `< 3` | +| `*` | `>= 0.0.0` | + + +#### Patch release or tilde (`~`) range comparison + +You can use the tilde (`~`) operator to make patch release comparisons. +This is useful when you want to specify a minor version up to the next major version. + +*Example patch release comparisons* +| Comparison | Equivalent | +|------------|---------------------| +| `~1.2.3` | `>= 1.2.3, < 1.3.0` | +| `~1` | `>= 1, <2` | +| `~2.3` | `>= 2.3, < 2.4` | +| `~1.2.x` | `>= 1.2.0, < 1.3.0` | +| `~1.x` | `>= 1, < 2` | + + +#### Major release or caret (`^`) range comparisons + +You can use the caret (`^`) operator to make major release comparisons after a stable, `1.0.0`, version is published. +If you make a major release comparison before a stable version is published, minor versions define the API stability level. -For more information about parsing, sorting, checking, and comparing version constraints, see the [Masterminds SemVer README](https://github.com/Masterminds/semver#semver). +*Example major release comparisons* -## Example CRs that specify a version range +| Comparison | Equivalent | +|------------|----------------------------------------| +| `^1.2.3` | `>= 1.2.3, < 2.0.0``>= 1.2.3, < 2.0.0` | +| `^1.2.x` | `>= 1.2.0, < 2.0.0` | +| `^2.3` | `>= 2.3, < 3` | +| `^2.x` | `>= 2.0.0, < 3` | +| `^0.2.3` | `>=0.2.3 <0.3.0` | +| `^0.2` | `>=0.2.0 <0.3.0` | +| `^0.0.3` | `>=0.0.3 <0.0.4` | +| `^0.0` | `>=0.0.0 <0.1.0` | +| `^0` | `>=0.0.0 <1.0.0` | From 164bb28f70011347ebf4483700903a50adbcfc88 Mon Sep 17 00:00:00 2001 From: Michael Ryan Peter Date: Mon, 27 Nov 2023 10:04:14 -0500 Subject: [PATCH 3/3] Apply review feedback - Close parenthesis on line 11 - Remove mention of hyphen range comparisons Signed-off-by: Michael Ryan Peter --- docs/drafts/version-ranges.md | 25 +++++++++---------------- 1 file changed, 9 insertions(+), 16 deletions(-) diff --git a/docs/drafts/version-ranges.md b/docs/drafts/version-ranges.md index bd7013ad4..6fabaf8d8 100644 --- a/docs/drafts/version-ranges.md +++ b/docs/drafts/version-ranges.md @@ -19,25 +19,18 @@ You define a version range by adding a comparison string to the `spec.version` f #### Basic comparisons -| Operator | Definition | -|----------|-----------------------------------| -| `=` | equal (not aliased to an operator | -| `!=` | not equal | -| `>` | greater than | -| `<` | less than | -| `>=` | greater than or equal to | -| `<=` | less than or equal to | +| Operator | Definition | +|----------|------------------------------------| +| `=` | equal (not aliased to an operator) | +| `!=` | not equal | +| `>` | greater than | +| `<` | less than | +| `>=` | greater than or equal to | +| `<=` | less than or equal to | #### Range comparisons -OLM 1.0 does not support hypen range comparisons. -For example, the following range option is not supported: - - ```yaml - version: 3.0 - 3.6 - ``` - -To specify a version range, use a method similar to the following example: +To specify a version range, use a range comparison similar to the following example: ```yaml version: >=3.0, <3.6