OPRUN-4195,OPRUN-4275,OPRUN-4276: release bundle attribute in version property

[grokspawn]

Description of the change:
Adds a new bundle-scoped "release" flag to the existing version property to allow for more sophisticated replacement strategies with improved transparency.
Adds a new substitutesFor catalog template to help folks trivially adopt the new approaches and avoid common error scenarios.

Motivation for the change:
As brief and RFC state, the imperative upgrade graph building process had a CSV attribute "substitutesFor" which allowed tooling to perform bundle-level replacement in resulting graphs. We had no equivalent FBC approach to the problem where there is a packaging-only change which we need to insert into an existing graph in a way that it didn't pretend to be the original bundle, but made it possible to prefer the new bundle over the old one, and even upgrade from the old to the new.

Reviewer Checklist

• Implementation matches the proposed design, or proposal is updated to match implementation
• Sufficient unit test coverage
• Sufficient end-to-end test coverage
• Docs updated or added to /docs
• Commit messages sensible and descriptive

[openshift-ci]

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign camilamacedo86 for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[codecov]

Codecov Report

❌ Patch coverage is 58.98618% with 89 lines in your changes missing coverage. Please review.
✅ Project coverage is 57.51%. Comparing base (91e49e4) to head (cb43dd4).

Files with missing lines	Patch %	Lines
alpha/template/substitutes/substitutes.go	65.55%	24 Missing and 7 partials ⚠️
alpha/template/converter/converter.go	0.00%	21 Missing ⚠️
alpha/model/model.go	81.81%	6 Missing and 2 partials ⚠️
pkg/lib/validation/bundle.go	20.00%	6 Missing and 2 partials ⚠️
pkg/registry/csv.go	45.45%	5 Missing and 1 partial ⚠️
pkg/registry/parse.go	64.70%	3 Missing and 3 partials ⚠️
pkg/registry/bundle.go	55.55%	2 Missing and 2 partials ⚠️
pkg/registry/registry_to_model.go	40.00%	2 Missing and 1 partial ⚠️
alpha/declcfg/declcfg_to_model.go	75.00%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##           master    #1792    +/-   ##
========================================
  Coverage   57.50%   57.51%            
========================================
  Files         136      137     +1     
  Lines       12934    13123   +189     
========================================
+ Hits         7438     7548   +110     
- Misses       4341     4402    +61     
- Partials     1155     1173    +18     

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[grokspawn]

Please note that this repo's merge method is set to squash, so all of these commits will get squished to a single one even if I forget to do it manually.

They're preserved here mostly because there has been a lot of ground covered over the lifetime of this feature w.r.t. different implementation strategies, and I didn't want to lose that.

[grokspawn]

Needs to land after operator-framework/api#454 merges and a new o-f/api release is cut.
/hold

[grokspawn]

merge blocked by operator-framework/api#454

[grokspawn]

/hold cancel
v0.37.0 of o-f/api has been published.

[openshift-ci-robot]

@grokspawn: This pull request references OPRUN-4195 which is a valid jira issue.

Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the story to target the "4.22.0" version, but no target version was set.

This pull request references OPRUN-4275 which is a valid jira issue.

Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the story to target the "4.22.0" version, but no target version was set.

This pull request references OPRUN-4276 which is a valid jira issue.

Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the story to target the "4.22.0" version, but no target version was set.

Details

In response to this:

Description of the change:
Adds a new bundle-scoped "release" flag to the existing version property to allow for more sophisticated replacement strategies with improved transparency.
Adds a new substitutesFor catalog template to help folks trivially adopt the new approaches and avoid common error scenarios.

Motivation for the change:
As brief and RFC state, the imperative upgrade graph building process had a CSV attribute "substitutesFor" which allowed tooling to perform bundle-level replacement in resulting graphs. We had no equivalent FBC approach to the problem where there is a packaging-only change which we need to insert into an existing graph in a way that it didn't pretend to be the original bundle, but made it possible to prefer the new bundle over the old one, and even upgrade from the old to the new.

Reviewer Checklist

• Implementation matches the proposed design, or proposal is updated to match implementation
• Sufficient unit test coverage
• Sufficient end-to-end test coverage
• Docs updated or added to /docs
• Commit messages sensible and descriptive

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

[Copilot]

Pull request overview

This PR adds a new bundle-scoped "release" flag to the existing version property to enable more sophisticated replacement strategies with improved transparency. It introduces a new "substitutesFor" catalog template to help users adopt these approaches while avoiding common error scenarios. The implementation updates the API dependency from v0.36.0 to v0.37.0 and provides comprehensive support for release versioning throughout the registry and model layers.

Key Changes:

• Adds Release field to PackageProperty and Bundle structures with corresponding parsing and validation logic
• Implements a new substitutes template for declaratively managing bundle substitutions in upgrade graphs
• Updates property builders and model validation to handle release versions with semantic versioning constraints

Reviewed changes

Copilot reviewed 19 out of 20 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
pkg/registry/types.go	Adds Release field to PackageProperty struct
pkg/registry/csv.go	Implements GetRelease() method to extract release version from CSV spec
pkg/registry/bundle.go	Adds Release() method to Bundle type for accessing release version
pkg/registry/parse.go	Implements release version extraction from build metadata for substitutesFor bundles
pkg/registry/registry_to_model.go	Updates bundle property creation to include release version
pkg/lib/validation/bundle.go	Adds validation for CSV release version parsing
alpha/property/property.go	Adds Release field and MustBuildPackageRelease helper function
alpha/model/model.go	Adds Release field to Bundle, implements version string formatting and name normalization
alpha/declcfg/declcfg_to_model.go	Parses and validates release version from package properties
alpha/template/substitutes/substitutes.go	New template implementation for bundle substitution workflows
cmd/opm/alpha/template/substitutes.go	CLI command for rendering substitutes templates
cmd/opm/alpha/template/cmd.go	Integrates substitutes command into template subcommands
cmd/opm/alpha/convert-template/convert.go	Adds substitutes converter command
alpha/template/converter/converter.go	Extends converter to support substitutes template type
go.mod, go.sum	Updates operator-framework/api dependency to v0.37.0
Test files	Comprehensive test coverage for release version functionality and substitutes template

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jianzhangbjz]

cc: @Xia-Zhao-rh ^^