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

api/v1/clusterextension_types.go

@@ -466,6 +466,28 @@ type BundleMetadata struct {
 	// +required
 	// +kubebuilder:validation:XValidation:rule="self.matches(\"^([0-9]+)(\\\\.[0-9]+)?(\\\\.[0-9]+)?(-([-0-9A-Za-z]+(\\\\.[-0-9A-Za-z]+)*))?(\\\\+([-0-9A-Za-z]+(-\\\\.[-0-9A-Za-z]+)*))?\")",message="version must be well-formed semver"
 	Version string `json:"version"`
+
+	// release is an optional field that identifies a specific release of this bundle's version.
+	// A release represents a re-publication of the same version, typically used to deliver
+	// packaging or metadata changes without changing the version number. When multiple
+	// releases exist for the same version, higher releases are preferred. An unset release
+	// is less preferred than all other release values.
+	//
+	// The value consists of dot-separated identifiers, where each identifier is either a
+	// numeric value (without leading zeros) or an alphanumeric string (e.g., "2", "1.el9",
+	// "3.alpha.1"). Releases are compared identifier by identifier: numeric identifiers are
+	// compared as integers, alphanumeric identifiers are compared lexically, and numeric
+	// identifiers always sort before alphanumeric identifiers.
+	//
+	// For bundles with explicit pkg.Release metadata, this field contains that release value.
+	// For registry+v1 bundles lacking an explicit release value, this field contains the release
+	// extracted from version's build metadata (e.g., '2' from '1.0.0+2').
+	// This field is omitted when the bundle's release value is unset.
+	//
+	// +optional
+	// <opcon:experimental>
+	// +kubebuilder:validation:XValidation:rule="self.matches(\"^$|^(0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(\\\\.(0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*$\")",message="release must be empty or consist of dot-separated identifiers (numeric without leading zeros, or alphanumeric)"
+	Release *string `json:"release,omitempty"`
 }
 
 // RevisionStatus defines the observed state of a ClusterObjectSet.

docs/api-reference/olmv1-api-reference.md

@@ -67,6 +67,7 @@ _Appears in:_
 | --- | --- | --- | --- |
 | `name` _string_ | name is required and follows the DNS subdomain standard as defined in [RFC 1123].<br />It must contain only lowercase alphanumeric characters, hyphens (-) or periods (.),<br />start and end with an alphanumeric character, and be no longer than 253 characters. |  | Required: \{\} <br /> |
 | `version` _string_ | version is required and references the version that this bundle represents.<br />It follows the semantic versioning standard as defined in https://semver.org/. |  | Required: \{\} <br /> |
+| `release` _string_ | release is an optional field that identifies a specific release of this bundle's version.<br />A release represents a re-publication of the same version, typically used to deliver<br />packaging or metadata changes without changing the version number. When multiple<br />releases exist for the same version, higher releases are preferred. An unset release<br />is less preferred than all other release values.<br />The value consists of dot-separated identifiers, where each identifier is either a<br />numeric value (without leading zeros) or an alphanumeric string (e.g., "2", "1.el9",<br />"3.alpha.1"). Releases are compared identifier by identifier: numeric identifiers are<br />compared as integers, alphanumeric identifiers are compared lexically, and numeric<br />identifiers always sort before alphanumeric identifiers.<br />For bundles with explicit pkg.Release metadata, this field contains that release value.<br />For registry+v1 bundles lacking an explicit release value, this field contains the release<br />extracted from version's build metadata (e.g., '2' from '1.0.0+2').<br />This field is omitted when the bundle's release value is unset.<br /><opcon:experimental> |  | Optional: \{\} <br /> |
 
 
 #### CRDUpgradeSafetyEnforcement

helm/experimental.yaml

@@ -14,6 +14,7 @@ options:
         - HelmChartSupport
         - BoxcutterRuntime
         - DeploymentConfig
+        - BundleReleaseSupport
       disabled:
         - WebhookProviderOpenshiftServiceCA
 # List of enabled experimental features for catalogd

helm/olmv1/base/operator-controller/crd/experimental/olm.operatorframework.io_clusterextensions.yaml

@@ -688,6 +688,29 @@ spec:
                             hyphens (-) or periods (.), start and end with an alphanumeric
                             character, and be no longer than 253 characters
                           rule: self.matches("^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$")
+                      release:
+                        description: |-
+                          release is an optional field that identifies a specific release of this bundle's version.
+                          A release represents a re-publication of the same version, typically used to deliver
+                          packaging or metadata changes without changing the version number. When multiple
+                          releases exist for the same version, higher releases are preferred. An unset release
+                          is less preferred than all other release values.
+
+                          The value consists of dot-separated identifiers, where each identifier is either a
+                          numeric value (without leading zeros) or an alphanumeric string (e.g., "2", "1.el9",
+                          "3.alpha.1"). Releases are compared identifier by identifier: numeric identifiers are
+                          compared as integers, alphanumeric identifiers are compared lexically, and numeric
+                          identifiers always sort before alphanumeric identifiers.
+
+                          For bundles with explicit pkg.Release metadata, this field contains that release value.
+                          For registry+v1 bundles lacking an explicit release value, this field contains the release
+                          extracted from version's build metadata (e.g., '2' from '1.0.0+2').
+                          This field is omitted when the bundle's release value is unset.
+                        type: string
+                        x-kubernetes-validations:
+                        - message: release must be empty or consist of dot-separated
+                            identifiers (numeric without leading zeros, or alphanumeric)
+                          rule: self.matches("^$|^(0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(\\.(0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*$")
                       version:
                         description: |-
                           version is required and references the version that this bundle represents.

internal/operator-controller/bundle/versionrelease.go

@@ -85,6 +85,19 @@ func (vr *VersionRelease) AsLegacyRegistryV1Version() bsemver.Version {
 
 type Release []bsemver.PRVersion
 
+// String returns the string representation of the release.
+// Returns an empty string if the release is nil or empty.
+func (r Release) String() string {
+	if len(r) == 0 {
+		return ""
+	}
+	parts := make([]string, len(r))
+	for i, pr := range r {
+		parts[i] = pr.String()
+	}
+	return strings.Join(parts, ".")
+}
+
 // Compare compares two Release values. It returns:
 //
 //	-1 if r < other

internal/operator-controller/bundleutil/bundle.go

@@ -11,34 +11,99 @@ import (
 
 	ocv1 "github.com/operator-framework/operator-controller/api/v1"
 	"github.com/operator-framework/operator-controller/internal/operator-controller/bundle"
+	"github.com/operator-framework/operator-controller/internal/operator-controller/features"
 )
 
 func GetVersionAndRelease(b declcfg.Bundle) (*bundle.VersionRelease, error) {
 	for _, p := range b.Properties {
 		if p.Type == property.TypePackage {
-			var pkg property.Package
-			if err := json.Unmarshal(p.Value, &pkg); err != nil {
-				return nil, fmt.Errorf("error unmarshalling package property: %w", err)
-			}
-
-			// TODO: For now, we assume that all bundles are registry+v1 bundles.
-			//   In the future, when we support other bundle formats, we should stop
-			//   using the legacy mechanism (i.e. using build metadata in the version)
-			//   to determine the bundle's release.
-			vr, err := bundle.NewLegacyRegistryV1VersionRelease(pkg.Version)
-			if err != nil {
-				return nil, err
-			}
-			return vr, nil
+			return parseVersionRelease(p.Value)
 		}
 	}
 	return nil, fmt.Errorf("no package property found in bundle %q", b.Name)
 }
 
-// MetadataFor returns a BundleMetadata for the given bundle name and version.
-func MetadataFor(bundleName string, bundleVersion bsemver.Version) ocv1.BundleMetadata {
+func parseVersionRelease(pkgData json.RawMessage) (*bundle.VersionRelease, error) {
+	var pkg property.Package
+	if err := json.Unmarshal(pkgData, &pkg); err != nil {
+		return nil, fmt.Errorf("error unmarshalling package property: %w", err)
+	}
+
+	// Check if release field is explicitly present in JSON (even if empty).
+	// property.Package has Release string, so we can't distinguish "field absent" from "field empty".
+	// We unmarshal again into a helper struct with Release *string to detect presence.
+	var releaseField struct {
+		Release *string `json:"release"`
+	}
+	if err := json.Unmarshal(pkgData, &releaseField); err != nil {
+		return nil, fmt.Errorf("error unmarshalling package release field: %w", err)
+	}
+
+	// When BundleReleaseSupport is enabled and bundle has explicit release field, use it.
+	if features.OperatorControllerFeatureGate.Enabled(features.BundleReleaseSupport) && releaseField.Release != nil {
+		return parseExplicitRelease(pkg.Version, *releaseField.Release)
+	}
+
+	// Fall back to legacy registry+v1 behavior (release in build metadata)
+	//
+	// TODO: For now, we assume that all bundles are registry+v1 bundles.
+	//   In the future, for supporting other bundle formats, we should not
+	//   use the legacy registry+v1 mechanism (i.e. using build metadata in
+	//   the version) to determine the bundle's release.
+	vr, err := bundle.NewLegacyRegistryV1VersionRelease(pkg.Version)
+	if err != nil {
+		return nil, err
+	}
+	return vr, nil
+}
+
+// parseExplicitRelease parses version and release from separate fields.
+// Build metadata is preserved in the version because with an explicit release field,
+// build metadata serves its proper semver purpose (e.g., git commit, build number).
+// In contrast, NewLegacyRegistryV1VersionRelease clears build metadata because it
+// interprets build metadata AS the release value for registry+v1 bundles.
+func parseExplicitRelease(version, releaseStr string) (*bundle.VersionRelease, error) {
+	vers, err := bsemver.Parse(version)
+	if err != nil {
+		return nil, fmt.Errorf("error parsing version %q: %w", version, err)
+	}
+
+	var rel bundle.Release
+	if releaseStr == "" {
+		// Explicit empty release: use empty slice (not nil)
+		rel = bundle.Release([]bsemver.PRVersion{})
+	} else {
+		rel, err = bundle.NewRelease(releaseStr)
+		if err != nil {
+			return nil, fmt.Errorf("error parsing release %q: %w", releaseStr, err)
+		}
+	}
+
+	return &bundle.VersionRelease{
+		Version: vers,
+		Release: rel,
+	}, nil
+}
+
+// MetadataFor returns a BundleMetadata for the given bundle name and version/release.
+func MetadataFor(bundleName string, vr bundle.VersionRelease) ocv1.BundleMetadata {
+	if features.OperatorControllerFeatureGate.Enabled(features.BundleReleaseSupport) {
+		// New behavior: separate Version and Release fields
+		bm := ocv1.BundleMetadata{
+			Name:    bundleName,
+			Version: vr.Version.String(),
+		}
+		if vr.Release != nil {
+			relStr := vr.Release.String()
+			bm.Release = &relStr
+		}
+		return bm
+	}
+	// Old behavior for backward compatibility: reconstitute build metadata in Version field
+	// This preserves release information (e.g., "1.0.0+2") for standard CRD users where
+	// the Release field is pruned by the API server.
 	return ocv1.BundleMetadata{
 		Name:    bundleName,
-		Version: bundleVersion.String(),
+		Version: vr.AsLegacyRegistryV1Version().String(),
 	}
 }