📖 Docs for version range support #544

michaelryanpeter · 2023-11-16T20:16:42Z

Description

Add docs about version range support. Create a drafts docs folder. This folder is for docs that are drafts to iterate on and not published as part of the customer-facing docs.

Closes #407.

Reviewer Checklist

API Go Documentation
Tests: Unit Tests (and E2E Tests, if appropriate)
Comprehensive Commit Messages
Links to related GitHub Issue(s)

Add docs explaining version range. Signed-off-by: Michael Ryan Peter <mipeter@redhat.com>

docs/drafts/version-ranges.md

joelanford · 2023-11-16T21:01:15Z

docs/drafts/version-ranges.md

+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.


I would expect this doc to be purely about spec.version, so I'd suggest striking this.

In a higher-level doc, I'd expect something that talks about the various spec fields and their interactions.

joelanford · 2023-11-16T21:05:33Z

docs/drafts/version-ranges.md

+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.


latest

Technically, it's the latest version that satisfies resolution. I think it's important to call that out pretty clearly somewhere, and possibly explain with an example.

For example:

In the catalog:

packageA v1.0.0 exists and depends on packageB v1.2.0

packageB v1.2.0 exists

packageB v1.2.1 exists

On the cluster:

Operator for packageA says spec.version: 1.0.0

Operator for packageB says spec.version: 1.2.x

The version that will ultimately be chosen for packageB is 1.2.0 even though 1.2.1 is available, because that's what packageA requires.

For the moment, I linked to Deppy's README to explain resolution. WDYT of creating a follow up issue to port the OCP docs about dependency resolution upstream?

michaelryanpeter · 2023-11-20T20:19:17Z

docs/drafts/version-ranges.md

+| `<`      | less than                         |
+| `>=`     | greater than or equal to          |
+| `<=`     | less than or equal to             |
+


I created #550 to add docs on working with pre-releases

- Remove references to the Mastermind SemVer docs - Define operators and comparisons - Address review feedback Signed-off-by: Michael Ryan Peter <mipeter@redhat.com>

michaelryanpeter · 2023-11-20T20:36:17Z

docs/drafts/version-ranges.md

+
+You define a version range in an Operator's custom resource (CR) file.
+
+## Specifying a version range in the CR


I removed the other sections on the spec.version field. They didn't make sense with the expanded content, and I think it will take a bit more work to incorporate the content into one doc on the spec.version field. I created a follow up issue here: #551

michaelryanpeter · 2023-11-20T20:39:39Z

docs/drafts/version-ranges.md

@@ -0,0 +1,93 @@
+# Operator version ranges


I created a follow up issue to add example CRs to the doc: #552

everettraven

This doc looks great to me! I noticed one small thing:

everettraven · 2023-11-22T15:09:55Z

docs/drafts/version-ranges.md

+
+| Operator | Definition                        |
+|----------|-----------------------------------|
+| `=`      | equal (not aliased to an operator |


Addressed in 164bb28

tmshort · 2023-11-27T14:47:04Z

docs/drafts/version-ranges.md

+
+#### Range comparisons
+
+OLM 1.0 does not support hypen range comparisons.


Suggested change

OLM 1.0 does not support hypen range comparisons.

OLM 1.0 does not support hyphen range comparisons.

Do we need to mention hyphen ranges at all? If we're not mentioning Masterminds, should we?

Addressed in 164bb28

- Close parenthesis on line 11 - Remove mention of hyphen range comparisons Signed-off-by: Michael Ryan Peter <mipeter@redhat.com>

codecov · 2023-11-27T15:40:54Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (6cb56f7) 78.59% compared to head (164bb28) 83.72%.
Report is 5 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #544      +/-   ##
==========================================
+ Coverage   78.59%   83.72%   +5.13%     
==========================================
  Files          18       20       +2     
  Lines         766      811      +45     
==========================================
+ Hits          602      679      +77     
+ Misses        131       91      -40     
- Partials       33       41       +8

Flag	Coverage Δ
e2e	`63.62% <ø> (?)`
unit	`78.54% <ø> (-0.05%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

Issue operator-framework#407: Docs for version range support

76a1ac1

Add docs explaining version range. Signed-off-by: Michael Ryan Peter <mipeter@redhat.com>

michaelryanpeter requested a review from a team as a code owner November 16, 2023 20:16

michaelryanpeter commented Nov 16, 2023

View reviewed changes

docs/drafts/version-ranges.md Outdated Show resolved Hide resolved

michaelryanpeter commented Nov 16, 2023

View reviewed changes

docs/drafts/version-ranges.md Outdated Show resolved Hide resolved

michaelryanpeter changed the title ~~📖 Issue #407: Docs for version range support~~ WIP: 📖 Docs for version range support Nov 16, 2023

openshift-ci bot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Nov 16, 2023

michaelryanpeter changed the title ~~WIP: 📖 Docs for version range support~~ [WIP] 📖 Docs for version range support Nov 16, 2023

michaelryanpeter changed the title ~~[WIP] 📖 Docs for version range support~~ [WIP] Docs for version range support Nov 16, 2023

michaelryanpeter changed the title ~~[WIP] Docs for version range support~~ WIP: 📖 Docs for version range support Nov 16, 2023

michaelryanpeter changed the title ~~WIP: 📖 Docs for version range support~~ WIP: 📖 Docs for version range support Nov 16, 2023

michaelryanpeter changed the title ~~WIP: 📖 Docs for version range support~~ 📖 Docs for version range support Nov 16, 2023

openshift-ci bot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Nov 16, 2023

michaelryanpeter changed the title ~~📖 Docs for version range support~~ 📖 WIP Docs for version range support Nov 16, 2023

michaelryanpeter changed the title ~~📖 WIP Docs for version range support~~ WIP: 📖 Docs for version range support Nov 16, 2023

openshift-ci bot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Nov 16, 2023

joelanford reviewed Nov 16, 2023

View reviewed changes

docs/drafts/version-ranges.md Outdated Show resolved Hide resolved

joelanford reviewed Nov 16, 2023

View reviewed changes

michaelryanpeter force-pushed the issue-407-opctl-version-range-docs branch from fd0bc69 to 57270d7 Compare November 20, 2023 20:08

michaelryanpeter mentioned this pull request Nov 20, 2023

[Docs] Update version range docs about pre-release versions and SemVer #550

Open

michaelryanpeter commented Nov 20, 2023

View reviewed changes

Address feedback. Define operators and comparisons.

a112f0f

- Remove references to the Mastermind SemVer docs - Define operators and comparisons - Address review feedback Signed-off-by: Michael Ryan Peter <mipeter@redhat.com>

michaelryanpeter force-pushed the issue-407-opctl-version-range-docs branch from eb455f6 to a112f0f Compare November 20, 2023 20:30

michaelryanpeter mentioned this pull request Nov 20, 2023

[Docs] Create docs for spec.version field #551

Open

michaelryanpeter commented Nov 20, 2023

View reviewed changes

michaelryanpeter mentioned this pull request Nov 20, 2023

[Docs] Add example CRs to version range docs #552

Open

michaelryanpeter commented Nov 20, 2023

View reviewed changes

michaelryanpeter changed the title ~~WIP: 📖 Docs for version range support~~ 📖 Docs for version range support Nov 20, 2023

openshift-ci bot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Nov 20, 2023

everettraven reviewed Nov 22, 2023

View reviewed changes

tmshort reviewed Nov 27, 2023

View reviewed changes

Apply review feedback

164bb28

- Close parenthesis on line 11 - Remove mention of hyphen range comparisons Signed-off-by: Michael Ryan Peter <mipeter@redhat.com>

michaelryanpeter force-pushed the issue-407-opctl-version-range-docs branch from e2a521b to 164bb28 Compare November 27, 2023 15:07

everettraven approved these changes Nov 27, 2023

View reviewed changes

m1kola added this pull request to the merge queue Nov 28, 2023

Merged via the queue into operator-framework:main with commit 1f84177 Nov 28, 2023
15 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

📖 Docs for version range support #544

📖 Docs for version range support #544

michaelryanpeter commented Nov 16, 2023 •

edited

Loading

joelanford Nov 16, 2023

michaelryanpeter Nov 20, 2023

joelanford Nov 16, 2023

michaelryanpeter Nov 20, 2023

michaelryanpeter Nov 20, 2023 •

edited

Loading

michaelryanpeter Nov 20, 2023

michaelryanpeter Nov 20, 2023

everettraven left a comment

everettraven Nov 22, 2023

michaelryanpeter Nov 27, 2023

tmshort Nov 27, 2023

tmshort Nov 27, 2023

michaelryanpeter Nov 27, 2023

codecov bot commented Nov 27, 2023


		You define a version range in an Operator's custom resource (CR) file.

		## Specifying a version range in the CR

	\| `=` \| equal (not aliased to an operator \|
	\| `=` \| equal (not aliased to an operator) \|


		#### Range comparisons

		OLM 1.0 does not support hypen range comparisons.

	OLM 1.0 does not support hypen range comparisons.
	OLM 1.0 does not support hyphen range comparisons.

📖 Docs for version range support #544

📖 Docs for version range support #544

Conversation

michaelryanpeter commented Nov 16, 2023 • edited Loading

Description

Reviewer Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

michaelryanpeter Nov 20, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

everettraven left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov bot commented Nov 27, 2023

Codecov Report

michaelryanpeter commented Nov 16, 2023 •

edited

Loading

michaelryanpeter Nov 20, 2023 •

edited

Loading