Skip to content

Commit

Permalink
Address feedback. Define operators and comparisons.
Browse files Browse the repository at this point in the history 
- Remove references to the Mastermind SemVer docs
- Define operators and comparisons
- Address review feedback

Signed-off-by: Michael Ryan Peter <mipeter@redhat.com>
  • Loading branch information
@michaelryanpeter
michaelryanpeter committed Nov 20, 2023
1 parent 76a1ac1 commit 57270d7
Showing 1 changed file with 86 additions and 25 deletions.
111 changes: 86 additions & 25 deletions docs/drafts/version-ranges.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,47 +3,108 @@
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.
## Not specifying a version in the CR

Specifying a version in the CR
: Installs or updates the specified version.
Updates are not applied automatically.
If you do not specify a version in the Operator's CR, OLM 1.0 installs or updates the latest version of the Operator that can be resolved.
The resolved version is the latest version of the Operator that satisfies the dependencies and constraints of the Operator and the environment.
Updates that can be resolved are applied automatically when they are published to the catalog.

For more information about dependency 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)

// Should be consider porting the OCP dependency resolution docs upstream?
// https://docs.openshift.com/container-platform/4.14/operators/olm_v1/arch/olmv1-dependency.html

## Specifying a version in the CR

If you specify a version in the Operator's CR, OLM 1.0 installs or updates the specified version.
Operator 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

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.
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 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.
A comparison string is composed of a list of comma or space separated values and one or more 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 |

// Should we create an issue to add a section for pre-release versions?
// https://github.com/Masterminds/semver#working-with-prerelease-versionshttps://github.com/Masterminds/semver#working-with-prerelease-versions

#### 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 use 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` |

0 comments on commit 57270d7

Please sign in to comment.