✨ Support explicit pkg.Release field with build metadata fallback for bundle comparison

[rashmigottipati]

Description

Summary

Adds support for the explicit pkg.Release field in bundle metadata, enabling proper semantic versioning with release
information. When the BundleReleaseSupport feature gate is enabled, the comparison and sorting logic reads release information from the dedicated pkg.Release field (when present) instead of only using semver build metadata.

Key design decision: Re-releases require explicit channel entries (replaces/skips/skipRange) to be valid successors. The channel graph remains the sole authority on upgrade paths for registry+v1 bundles.

Changes

• Added BundleReleaseSupport feature gate (alpha, disabled by default)
• Feature-gated parsing: reads explicit pkg.Release when enabled, falls back to build metadata when disabled
• Build metadata is preserved when using explicit pkg.Release (serves its proper semver purpose)
• Updated ByVersionAndRelease(): uses Bundle.Compare() with build metadata fallback when enabled
• Re-releases must have explicit channel entries to be valid successors (no automatic bypass)
• Comprehensive test coverage with feature gate detection for both enabled/disabled paths

Feature Gate Behavior

Disabled (standard):

• Backward compatible - build metadata only
• Ignores explicit pkg.Release field
• Comparison/sorting uses legacy build metadata parsing

Enabled (experimental):

• Reads explicit pkg.Release field when present, falls back to build metadata
• Build metadata is preserved in version string
• Comparison/sorting uses Bundle.Compare() with fallback
• Supports both new bundle formats (with explicit release) and registry+v1 bundles (build metadata)
• Important: Does NOT bypass channel graph - re-releases require explicit channel entries

Reviewer Checklist

• API Go Documentation
• Tests: Unit Tests
• Comprehensive Commit Messages
• Links to related GitHub Issue(s)

Link to Github Issue: #2495
Epic: #2479

[netlify]

✅ Deploy Preview for olmv1 ready!

Name	Link
🔨 Latest commit	8d6dda3
🔍 Latest deploy log	https://app.netlify.com/projects/olmv1/deploys/69d6af65fe48be00077bbe36
😎 Deploy Preview	https://deploy-preview-2543--olmv1.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[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 kevinrizza 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

[Copilot]

Pull request overview

This PR introduces an alpha feature gate to allow OLMv1 upgrade resolution to treat “re-released” bundles (same semver, higher release/build value like 2.0.0+1 -> 2.0.0+2) as valid successors when explicitly enabled.

Changes:

• Added ReleaseVersionPriority feature gate (Alpha, default disabled).
• Added SameVersionHigherRelease() predicate and integrated it into SuccessorsOf() behind the feature gate.
• Added unit tests for SameVersionHigherRelease() and for SuccessorsOf() with the gate disabled.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
internal/operator-controller/features/features.go	Defines the new ReleaseVersionPriority feature gate and its spec.
internal/operator-controller/catalogmetadata/filter/successors.go	Conditionally expands successor matching to include same-version/higher-release bundles when gated on.
internal/operator-controller/catalogmetadata/filter/bundle_predicates.go	Adds the SameVersionHigherRelease() predicate.
internal/operator-controller/catalogmetadata/filter/bundle_predicates_test.go	Adds predicate unit tests including edge cases.
internal/operator-controller/catalogmetadata/filter/successors_test.go	Adds a regression test to ensure default (gate-off) behavior does not accept higher-release bundles.

---

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

[codecov]

Codecov Report

❌ Patch coverage is 85.29412% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 69.00%. Comparing base (fd25bf7) to head (8d6dda3).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
internal/operator-controller/bundleutil/bundle.go	90.00%	1 Missing and 1 partial ⚠️
...ator-controller/catalogmetadata/compare/compare.go	81.81%	1 Missing and 1 partial ⚠️
...or-controller/catalogmetadata/filter/successors.go	66.66%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2543      +/-   ##
==========================================
+ Coverage   68.95%   69.00%   +0.05%     
==========================================
  Files         139      139              
  Lines        9891     9915      +24     
==========================================
+ Hits         6820     6842      +22     
- Misses       2562     2563       +1     
- Partials      509      510       +1     

Flag	Coverage Δ
e2e	37.23% <20.58%> (-0.34%)	⬇️
experimental-e2e	52.14% <32.35%> (-0.09%)	⬇️
unit	53.67% <85.29%> (+0.07%)	⬆️

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.

🚀 New features to boost your workflow:

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

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

---

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

[joelanford]

If I understand this correctly, it looks like this introduces the new behavior that an explicit upgrade edge doesn't actually have to exist in the catalog to upgrade to a bundle that has the same version and a higher release. Is that the intent? (If so let's make that clear in the PR description).

Is it also the intent that we'll inherit the upgrade edges of the first release of the version?

[grokspawn]

We discussed earlier today. I think the first step is to essentially revert #2273 so that we're not attempting to interpret build metadata as release info anymore. Any catalogs built with tooling that supports release versioning will automagically propagate the build metadata into the CSV's spec.release field anyway, so regardless of whether the operator author used the old build metadata approach or the new spec.release approach, they would still have spec.release here.

The next step is to ensure that we're sorting successors using the CompositeVersion, which is easily performed if using the Bundle comparator during the sort.

This will prefer version+release over version.

#2273 makes the claim that future bundle types will drop this approach, not that registry+v1 bundles should. So that's my bad.
From the perspective of fulfilling handling precedents for registry+v1 bundles, we need to retain the ability to differentiate/order them by build metadata. :(

[grokspawn]

If I understand this correctly, it looks like this introduces the new behavior that an explicit upgrade edge doesn't actually have to exist in the catalog to upgrade to a bundle that has the same version and a higher release. Is that the intent? (If so let's make that clear in the PR description).

Is it also the intent that we'll inherit the upgrade edges of the first release of the version?

Sadly, we have to rely on the presence of existing graph edges or we break assumptions users have with the registry+v1 bundle format, coming from v0.

So even though we have the ability to prefer version+release over version, since replaces/skips use named bundles instead of bundle versions we have to support the older behavior.

[joelanford]

I think the first step is to essentially revert #2273 so that we're not attempting to interpret build metadata as release info anymore.

That would be a regression of a bug fix that #2273 made though, right?

Sadly, we have to rely on the presence of existing graph edges or we break assumptions users have with the registry+v1 bundle format, coming from v0.

So even though we have the ability to prefer version+release over version, since replaces/skips use named bundles instead of bundle versions we have to support the older behavior.

Yeah, agreed. I reached the same conclusion after thinking about this more.

So if I understand correctly now:

1. The existing code on main already honors the upgrade graph and orders "same version, different release" correctly when parsing from build metadata
2. The existing code on main knows nothing about the new release field.

So the change we need now is "look for release in the olm.package property, and if present, prefer it over build metadata"?

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

---

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

[grokspawn]

Adjusted my comments. I missed the part of the #2273 description when it said that we wouldn't divert from semver ordering for any new bundle formats.
From the perspective of registry+v1 bundles, this is precedent and we should support the new case with .spec.release is available, otherwise falling back on the 'is it bundle metadata' ordering logic.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

---

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

[rashmigottipati]

@grokspawn Done. Updated the PR to enable the feature gate in experimental release.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 4 comments.

---

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

[grokspawn]

@rashmigottipati would you please resolve the copilot comments in this review? I'm trying to not duplicate guidance with them, and it's challenging to know what is still current.

What I have been doing is:

• thumbs-up and resolve, for good feedback that I updated
• thumbs-down and resolve, for clear hallucinations or obvious craziness
• thumbs-down and DON'T resolve, for a disagreement I cannot dismiss (and we can talk more about).

WDYT?

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

---

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

[pedjak]

Thanks for the PR! Here are some review comments on the implementation.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

---

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

[joelanford]

This change feels off to me.

It seems like this function shouldn't change at all. The change, as I understand it, boils down to how we build a version/release.

Without the feature gate: Only do it the legacy way by inspecting/parsing build metadata

With the feature gate: If release field is set, parse it directly. Only if unset do we fall back to legacy registry+v1 build metadata parsing.

But then once we have a VersionRelease, the comparison is the same.

Am I missing something else?

[joelanford]

Maybe the thing I'm missing is:

• operator-registry has a CompositeVersion type
• operator-controller has a VersionRelease type.

These represent the same exact concept, and we're trying to move in the direction of using the operator-registry variant?

IMO, we shouldn't mix them. We should pick one and delete the other.

[grokspawn]

I completely agree that we need to consolidate to a single representative type.
This PR is not intended to force the type consistency yet, since if it adopted the CompositeVersion type right now it would lack a formal Release type which we determined was essential to encourage broad adoption.
It just provides the featuregate and the sensitivity to an explicit release version.
I'd intended to merge operator-framework/operator-registry#1938 and then we would have follow-ups to op-reg & op-con to adopt the base type consistently throughout.
I was just hoping to be able to merge the two PRs independently.

[joelanford]

So WDYT about this PR focusing on "if release explicitly set, load it into VersionRelease value". And then a later PR comes in a moves everything over to the operator-registry types/comparisons?

[joelanford]

Comparing at the bundle level seems incorrect to me based on the name of this function. What if the bundle comparison method considers more than the version and release?

Seems like we'd want b2.CompositeVersion.Compare(&b1.CompositeVersion) or something like that?

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

---

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