Skip to content

Commit fd0bc69

Browse files
michaelryanpetermichaelryanpeter
committed
Address feedback. Define operators and comparisons.
- Remove references to the Mastermind SemVer docs - Define operators and comparisons - Address review feedback
1 parent 76a1ac1 commit fd0bc69

File tree

1 file changed

+86
-25
lines changed

1 file changed

+86
-25
lines changed

‎docs/drafts/version-ranges.md

Lines changed: 86 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -3,47 +3,108 @@
33
This document explains how to specify a version range to install or update an Operator with OLM 1.0.
44

55
You define an Operator's target version in its custom resource (CR) file.
6-
The following list describes how OLM resolves an Operator's target version, and the resulting actions:
76

8-
Not specifying a version in the CR
9-
: Installs or updates the latest version of the Operator.
10-
Updates are applied automatically when they are published to the catalog.
7+
## Not specifying a version in the CR
118

12-
Specifying a version in the CR
13-
: Installs or updates the specified version.
14-
Updates are not applied automatically.
9+
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.
10+
The resolved version is the latest version of the Operator that satisfies the dependencies and constraints of the Operator and the environment.
11+
Updates that can be resolved are applied automatically when they are published to the catalog.
12+
13+
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)
14+
15+
// Should be consider porting the OCP dependency resolution docs upstream?
16+
// https://docs.openshift.com/container-platform/4.14/operators/olm_v1/arch/olmv1-dependency.html
17+
18+
## Specifying a version in the CR
19+
20+
If you specify a version in the Operator's CR, OLM 1.0 installs or updates the specified version.
21+
Operator updates are not applied automatically.
1522
If you want to update the Operator, you must manually edit the CR and apply the changes to the cluster.
1623

17-
Specifying a channel
18-
: Installs or updates the latest version of the Operator in the channel.
19-
Updates are applied automatically when they are published to the specified channel.
24+
## Specifying a version range in the CR
25+
26+
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.
27+
Operator updates within the specified range are automatically installed if they can be resolved successfully.
28+
Updates are not installed if they are outside of the specified range or if they cannot be resolved successfully.
2029

21-
Specifying a version range in the CR
22-
: Installs or updates the latest version of the Operator within the version range.
23-
Updates that are within the specified range are automatically installed.
24-
Updates that are outside of the specified range are not installed.
30+
### Comparisons
2531

26-
The `spec.version` field uses the Masterminds `semver` package to enable the version range functionality.
32+
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.
2733

28-
OLM 1.0 does not support following methods for specifying a version range:
34+
#### Basic comparisons
2935

30-
* Using tags and labels are not supported.
31-
You must use semantic versioning to define a version range.
32-
* Using [hypen range comparisons](https://github.com/Masterminds/semver#hyphen-range-comparisons) are not supported.
36+
| Operator | Definition |
37+
|----------|-----------------------------------|
38+
| `=` | equal (not aliased to an operator |
39+
| `!=` | not equal |
40+
| `>` | greater than |
41+
| `<` | less than |
42+
| `>=` | greater than or equal to |
43+
| `<=` | less than or equal to |
44+
45+
// Should we create an issue to add a section for pre-release versions?
46+
// https://github.com/Masterminds/semver#working-with-prerelease-versionshttps://github.com/Masterminds/semver#working-with-prerelease-versions
47+
48+
#### Range comparisons
49+
50+
OLM 1.0 does not support hypen range comparisons.
3351
For example, the following range option is not supported:
3452

3553
```yaml
3654
version: 3.0 - 3.6
3755
```
3856
39-
To specify a range option, use a method similar to the following example:
57+
To specify a version range, use a method similar to the following example:
4058
41-
```yaml
42-
version: >=3.0 <3.6
43-
```
59+
```yaml
60+
version: >=3.0, <3.6
61+
```
62+
63+
#### Wildcards in comparisons
4464
4565
You can use the `x`, `X`, and `*` characters as wildcard characters in all comparison operations.
66+
If you use a wildcard character with the `=` operator, you define a patch level comparision.
67+
This is equivalent to making a tilde range comparison.
68+
69+
*Example comparisons with wildcard characters*
70+
| Comparison | Equivalent |
71+
|------------|---------------------|
72+
| `1.2.x` | `>= 1.2.0, < 1.3.0` |
73+
| `>= 1.2.x` | `>= 1.2.0` |
74+
| `<= 2.x` | `< 3` |
75+
| `*` | `>= 0.0.0` |
76+
77+
78+
#### Patch release or tilde (`~`) range comparison
79+
80+
You can use the tilde (`~`) operator to make patch release comparisons.
81+
This is useful when you want to specify a minor version up to the next major version.
82+
83+
*Example patch release comparisons*
84+
| Comparison | Equivalent |
85+
|------------|---------------------|
86+
| `~1.2.3` | `>= 1.2.3, < 1.3.0` |
87+
| `~1` | `>= 1, <2` |
88+
| `~2.3` | `>= 2.3, < 2.4` |
89+
| `~1.2.x` | `>= 1.2.0, < 1.3.0` |
90+
| `~1.x` | `>= 1, < 2` |
91+
92+
93+
#### Major release or caret (`^`) range comparisons
94+
95+
You can use the caret (`^`) operator to make major release comparisons after a stable, `1.0.0`, version is published.
96+
If you use make a major release comparison before a stable version is published, minor versions define the API stability level.
4697

47-
For more information about parsing, sorting, checking, and comparing version constraints, see the [Masterminds SemVer README](https://github.com/Masterminds/semver#semver).
98+
*Example major release comparisons*
4899

49-
## Example CRs that specify a version range
100+
| Comparison | Equivalent |
101+
|------------|----------------------------------------|
102+
| `^1.2.3` | `>= 1.2.3, < 2.0.0``>= 1.2.3, < 2.0.0` |
103+
| `^1.2.x` | `>= 1.2.0, < 2.0.0` |
104+
| `^2.3` | `>= 2.3, < 3` |
105+
| `^2.x` | `>= 2.0.0, < 3` |
106+
| `^0.2.3` | `>=0.2.3 <0.3.0` |
107+
| `^0.2` | `>=0.2.0 <0.3.0` |
108+
| `^0.0.3` | `>=0.0.3 <0.0.4` |
109+
| `^0.0` | `>=0.0.0 <0.1.0` |
110+
| `^0` | `>=0.0.0 <1.0.0` |

0 commit comments

Comments
 (0)