✨ Add support for parsing and persisting explicit pkg.Release field

[rashmigottipati]

Description

Summary

Adds support for parsing the explicit pkg.Release field from bundle metadata and persisting it through cluster storage (roundtripping). This is gated by the new BundleReleaseSupport alpha feature gate (disabled by default).

Changes

• Added BundleReleaseSupport alpha feature gate (disabled by default)
• Added Release field to BundleMetadata CRD type
• Added BundleReleaseKey label constant for annotation storage
• Updated bundleutil.parseVersionRelease() to: Parse explicit pkg.Release when feature gate enabled and field present. Fall back to legacy registry+v1 behavior (release in build metadata) otherwise
• Updated bundleutil.MetadataFor() to serialize release value from VersionRelease
• Added roundtripping support: store release in CRD field and annotations, read it back in filters and controllers

Feature Gate Behavior

When enabled:

• Bundles with explicit pkg.Release field: release parsed separately, build metadata preserved for proper semver purpose
• Bundles without explicit release: falls back to registry+v1 parsing (release from build metadata)

When feature gate disabled:

• All bundles use registry+v1 parsing (release from build metadata)
• Explicit pkg.Release field ignored

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	4519cc6
🔍 Latest deploy log	https://app.netlify.com/projects/olmv1/deploys/69d8691c7708360008a53770
😎 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 78.43137% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.93%. Comparing base (b6dfd40) to head (4519cc6).

Files with missing lines	Patch %	Lines
...or-controller/catalogmetadata/filter/successors.go	62.50%	3 Missing and 3 partials ⚠️
applyconfigurations/api/v1/bundlemetadata.go	0.00%	3 Missing ⚠️
internal/operator-controller/bundleutil/bundle.go	92.59%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2543      +/-   ##
==========================================
+ Coverage   68.91%   68.93%   +0.02%     
==========================================
  Files         139      139              
  Lines        9863     9900      +37     
==========================================
+ Hits         6797     6825      +28     
- Misses       2559     2565       +6     
- Partials      507      510       +3     

Flag	Coverage Δ
e2e	37.49% <31.37%> (-0.19%)	⬇️
experimental-e2e	52.05% <31.37%> (-0.25%)	⬇️
unit	53.65% <76.47%> (+0.11%)	⬆️

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.

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

[grokspawn]

Seems reasonable to me.

[rashmigottipati]

Thanks for the thorough review Joe. Your suggestions sound good to me. I've updated the PR to focus on:

• If pkg.Release is explicitly set (and feature gate enabled), parse it and load into VersionRelease value
• Roundtrip it through CRD field and annotations
• Removed all the changes to comparison logic

The type consolidation with operator-registry's CompositeVersion can happen in a follow-up PR once operator-framework/operator-registry#1938 is merged.

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

[Copilot]

Pull request overview

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

---

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

[Copilot]

Pull request overview

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

---

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