Docs: Implement full support for replaces, skips, and skipRange (and make default)

[joelanford]

User story

As an admin, when I have an installed ClusterExtension, I expect that the upgrade edges defined in the catalog (i.e. replaces, skips, and skipRange) will be honored.

List the user-facing issues in the epic that require documentation.

• Issue: [epic] Implement full support for replaces, skips, and skipRange (and make default) #738 (single issue epic)

Does this epic require new content or updates to existing content?

• Net-new content
• Update existing content

My assumption is that there are already docs that talk about how OLMv1 uses semver semantics when assessing upgrade successors in a channel. If that's true, those docs need to be updated to talk about replaces, skips, and skipRange.

Even with this new support for replaces, skips, and skipRange, OLMv1 logic is subtly different:

• In OLMv0 if there are multiple possible successors, the one closest to the channel head is chosen
• In OLMv1 if there are multiple possible successors, the one with the highest semver version is chosen.

What type of documentation is required for this epic?

• Release note
• Concept
• Procedure
• Reference
• Not sure

Is there prior art or reference materials that would help write the documentation?

https://olm.operatorframework.io/docs/concepts/olm-architecture/operator-catalog/creating-an-update-graph/

Documentation should be contributed to the docs/drafts/ directory

[michaelryanpeter]

/assign

[bentito]

And doc needs to clear up what the options are for upgradeConstraintPolicy and what this policy setting is expected to do when interacting with the honoring of skips, etc.

operator-controller/docs/drafts/upgrade-support.md

Line 48 in 9bbc444

## Manually verified upgrades and downgrades

see also:

https://issues.redhat.com/browse/OCPBUGS-33340

[joelanford]

To be clear, upgradeConstraintPolicy's behavior isn't what changed. What changed is the default algorithm we use to determine which bundles are candidates for upgrade.

So:

• upgradeConstraintPolicy: Enforce - "only allow the next version to come from the successors list"
• upgradeConstraintPolicy: Ignore - "do not limit the next version to the set of successors. instead allow any down/side/upgrade"

[michaelryanpeter]

/assign

[michaelryanpeter]

/unassign