Feature Overview (aka. Goal Summary)  

Operator authors can add optional guardrails to the semver-based upgrade flow to ensure that when an operator is upgraded, it passes through one or more specific versions or ranges before advancing.

Goals (aka. expected user outcomes)

OLM users (with sufficient permissions) will have full control over the pace of the operator update.  

• They can now easily see all available new versions for installed operators and the customized update graph defined by their channel, and version specifications.
• The update can be made by specifying a desired target version along the vendor-supplied update graph of the operator.  

This feature tracks the progress of:

• A mechanism (FBC schema) for operator/extension/package maintainers to customize the upgrade path in the catalog by specifying one (or more) versions (or version range) as an intermediate step(s) before advancing based on the semver-based upgrade flow.
• OLM 1.0 supports this new catalog attribute (FBC schema) in the semver-based upgrade flow.

Requirements (aka. Acceptance Criteria):

A list of specific needs or objectives that a feature must deliver in order to be considered complete.  Be sure to include nonfunctional requirements such as security, reliability, performance, maintainability, scalability, usability, etc.  Initial completion during Refinement status.

• The default versioning mechanism for a package is semver, i.e., 
  • No upgrades from 0.0.z to 0.0.z+n
  • You can update from 0.y.z to 0.y.z+n
  • You can update from 1.y.z to 1.y.z+n
  • You can update from 1.y.z to 1.y+j.z+n
  • You can’t update from stable to prerelease versions (by default)

• When upgrading an operator to version 1.2.3, a package author can require that you pass through 1.3.z before going to 1.4.z

• When upgrading an operator to version 1.2.3, a package author can require that you get to the latest 1.2.z before advancing to the next minor 1.3.z

• The package author can specify specific versions, or version ranges, that you must step through when upgrading

Anyone reviewing this Feature needs to know which deployment configurations that the Feature will apply to (or not) once it's been completed.  Describe specific needs (or indicate N/A) for each of the following deployment scenarios. For specific configurations that are out-of-scope for a given release, ensure you provide the OCPSTRAT (for the future to be supported configuration) as well.

Use Cases (Optional):

Include use case diagrams, main success scenarios, alternative flow scenarios.  Initial completion during Refinement status.

<your text here>

Questions to Answer (Optional):

Include a list of refinement / architectural questions that may need to be answered before coding can begin.  Initial completion during Refinement status.

<your text here>

Out of Scope

High-level list of items that are out of scope.  Initial completion during Refinement status.

<your text here>

Background

In an ideal world, every operator would strictly adhere to semantic versioning. Patch versions would only ever contain bug fixes. Minor version boundaries would only ever introduce optional new features while retaining backward compatibility. Major versions would be the only time breaking changes are allowed. Updates within a major version are always allowed, including going from 1.0.0 to 1.99.999.

Unfortunately, the reality is the landscape of operators in existence does not match this ideal. Sometimes, for example, an operator may include upgrade logic that must be executed when upgrading from any 1.1 version to any 1.2 version, but the developer removes this code in version 1.3. This means a user can’t upgrade directly from 1.1 to 1.3. To accommodate situations such as this one, OLM needs to give operator authors the ability to influence upgrades beyond traditional semantic versioning. Otherwise, it would be possible for users to skip required versions/ranges when upgrading, likely breaking their installations.

Upstream engineering brief: https://docs.google.com/document/d/1Zxp0aVF550rD9564lOtfiNKci4N03cp1D_fjoA7FKBo/edit?usp=sharing

Customer Considerations

Provide any additional customer-specific considerations that must be made when designing and delivering the Feature.  Initial completion during Refinement status.

<your text here>

Documentation Considerations

Provide information that needs to be considered and planned so that documentation will meet customer needs.  If the feature extends existing functionality, provide a link to its current documentation. Initial completion during Refinement status.

<your text here>

Interoperability Considerations

Which other projects, including ROSA/OSD/ARO, and versions in our portfolio does this feature impact?  What interoperability test scenarios should be factored by the layered products?  Initial completion during Refinement status.

<your text here>