add Release version as an optional field in the CSV

Makefile

@@ -129,7 +129,7 @@ $(YQ): $(LOCALBIN)
 	GOBIN=$(LOCALBIN) go install $(GO_INSTALL_OPTS) github.com/mikefarah/yq/v4@$(YQ_VERSION)
 
 .PHONY: kind
-kind: $(KIND) ## Download yq locally if necessary.
+kind: $(KIND) ## Download kind locally if necessary.
 $(KIND): $(LOCALBIN)
 	GOBIN=$(LOCALBIN) go install $(GO_INSTALL_OPTS) sigs.k8s.io/kind@latest
 

crds/operators.coreos.com_clusterserviceversions.yaml

@@ -27,6 +27,10 @@ spec:
           jsonPath: .spec.version
           name: Version
           type: string
+        - description: The release of this version of the CSV
+          jsonPath: .spec.release
+          name: Release
+          type: string
         - description: The name of a CSV that this one replaces
           jsonPath: .spec.replaces
           name: Replaces
@@ -8988,6 +8992,30 @@ spec:
                         type: string
                       name:
                         type: string
+                release:
+                  description: |-
+                    release specifies the packaging version of the operator, defaulting to empty
+                    release is optional
+
+                    A ClusterServiceVersion's release field is used to provide a secondary ordering
+                    for operators that share the same semantic version. This is useful for
+                    operators that need to make changes to the CSV which don't affect their functionality,
+                    for example:
+                    - to fix a typo in their description
+                    - to add/amend annotations or labels
+                    - to amend examples or documentation
+
+                    It is up to operator authors to determine the semantics of release versions they use
+                    for their operator.  All release versions must conform to the semver prerelease format
+                    (dot-separated identifiers containing only alphanumerics and hyphens) and are limited
+                    to a maximum length of 20 characters.
+                  type: string
+                  maxLength: 20
+                  x-kubernetes-validations:
+                    - rule: self.matches('^[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*$')
+                      message: release version must be composed of dot-separated identifiers containing only alphanumerics and hyphens
+                    - rule: '!self.split(''.'').exists(x, x.matches(''^0[0-9]+$''))'
+                      message: numeric identifiers in release version must not have leading zeros
                 replaces:
                   description: The name of a CSV this one replaces. Should match the `metadata.Name` field of the old CSV.
                   type: string

pkg/lib/release/release.go

@@ -0,0 +1,73 @@
+package release
+
+import (
+	"encoding/json"
+	"slices"
+	"strings"
+
+	semver "github.com/blang/semver/v4"
+)
+
+// +k8s:openapi-gen=true
+// OperatorRelease is a wrapper around a slice of semver.PRVersion which supports correct
+// marshaling to YAML and JSON.
+// +kubebuilder:validation:Type=string
+// +kubebuilder:validation:MaxLength=20
+// +kubebuilder:validation:XValidation:rule="self.matches('^[0-9A-Za-z-]+(\\\\.[0-9A-Za-z-]+)*$')",message="release version must be composed of dot-separated identifiers containing only alphanumerics and hyphens"
+// +kubebuilder:validation:XValidation:rule="!self.split('.').exists(x, x.matches('^0[0-9]+$'))",message="numeric identifiers in release version must not have leading zeros"
+type OperatorRelease struct {
+	Release []semver.PRVersion `json:"-"`
+}
+
+// DeepCopyInto creates a deep-copy of the Version value.
+func (v *OperatorRelease) DeepCopyInto(out *OperatorRelease) {
+	out.Release = slices.Clone(v.Release)
+}
+
+// MarshalJSON implements the encoding/json.Marshaler interface.
+func (v OperatorRelease) MarshalJSON() ([]byte, error) {
+	segments := []string{}
+	for _, segment := range v.Release {
+		segments = append(segments, segment.String())
+	}
+	return json.Marshal(strings.Join(segments, "."))
+}
+
+// UnmarshalJSON implements the encoding/json.Unmarshaler interface.
+func (v *OperatorRelease) UnmarshalJSON(data []byte) (err error) {
+	var versionString string
+
+	if err = json.Unmarshal(data, &versionString); err != nil {
+		return
+	}
+
+	segments := strings.Split(versionString, ".")
+	for _, segment := range segments {
+		release, err := semver.NewPRVersion(segment)
+		if err != nil {
+			return err
+		}
+		v.Release = append(v.Release, release)
+	}
+
+	return nil
+}
+
+// OpenAPISchemaType is used by the kube-openapi generator when constructing
+// the OpenAPI spec of this type.
+//
+// See: https://github.com/kubernetes/kube-openapi/tree/master/pkg/generators
+func (_ OperatorRelease) OpenAPISchemaType() []string { return []string{"string"} }
+
+// OpenAPISchemaFormat is used by the kube-openapi generator when constructing
+// the OpenAPI spec of this type.
+// "semver" is not a standard openapi format but tooling may use the value regardless
+func (_ OperatorRelease) OpenAPISchemaFormat() string { return "semver" }
+
+func (r OperatorRelease) String() string {
+	segments := []string{}
+	for _, segment := range r.Release {
+		segments = append(segments, segment.String())
+	}
+	return strings.Join(segments, ".")
+}

pkg/lib/release/release_test.go

@@ -0,0 +1,161 @@
+package release
+
+import (
+	"encoding/json"
+	"testing"
+
+	semver "github.com/blang/semver/v4"
+	"github.com/stretchr/testify/require"
+)
+
+func TestOperatorReleaseMarshal(t *testing.T) {
+	tests := []struct {
+		name string
+		in   OperatorRelease
+		out  []byte
+		err  error
+	}{
+		{
+			name: "single-segment",
+			in:   OperatorRelease{Release: []semver.PRVersion{mustNewPRVersion("1")}},
+			out:  []byte(`"1"`),
+		},
+		{
+			name: "two-segments",
+			in:   OperatorRelease{Release: []semver.PRVersion{mustNewPRVersion("1"), mustNewPRVersion("0")}},
+			out:  []byte(`"1.0"`),
+		},
+		{
+			name: "multi-segment",
+			in: OperatorRelease{Release: []semver.PRVersion{
+				mustNewPRVersion("1"),
+				mustNewPRVersion("2"),
+				mustNewPRVersion("3"),
+			}},
+			out: []byte(`"1.2.3"`),
+		},
+		{
+			name: "numeric-segments",
+			in: OperatorRelease{Release: []semver.PRVersion{
+				mustNewPRVersion("20240101"),
+				mustNewPRVersion("12345"),
+			}},
+			out: []byte(`"20240101.12345"`),
+		},
+		{
+			name: "alphanumeric-segments",
+			in: OperatorRelease{Release: []semver.PRVersion{
+				mustNewPRVersion("alpha"),
+				mustNewPRVersion("beta"),
+				mustNewPRVersion("1"),
+			}},
+			out: []byte(`"alpha.beta.1"`),
+		},
+		{
+			name: "alphanumeric-with-hyphens",
+			in: OperatorRelease{Release: []semver.PRVersion{
+				mustNewPRVersion("rc-1"),
+				mustNewPRVersion("build-123"),
+			}},
+			out: []byte(`"rc-1.build-123"`),
+		},
+		{
+			name: "mixed-alphanumeric",
+			in: OperatorRelease{Release: []semver.PRVersion{
+				mustNewPRVersion("1"),
+				mustNewPRVersion("2-beta"),
+				mustNewPRVersion("x86-64"),
+			}},
+			out: []byte(`"1.2-beta.x86-64"`),
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			m, err := tt.in.MarshalJSON()
+			require.Equal(t, tt.out, m, string(m))
+			require.Equal(t, tt.err, err)
+		})
+	}
+}
+
+func TestOperatorReleaseUnmarshal(t *testing.T) {
+	type TestStruct struct {
+		Release OperatorRelease `json:"r"`
+	}
+	tests := []struct {
+		name string
+		in   []byte
+		out  TestStruct
+		err  error
+	}{
+		{
+			name: "single-segment",
+			in:   []byte(`{"r": "1"}`),
+			out:  TestStruct{Release: OperatorRelease{Release: []semver.PRVersion{mustNewPRVersion("1")}}},
+		},
+		{
+			name: "two-segments",
+			in:   []byte(`{"r": "1.0"}`),
+			out:  TestStruct{Release: OperatorRelease{Release: []semver.PRVersion{mustNewPRVersion("1"), mustNewPRVersion("0")}}},
+		},
+		{
+			name: "multi-segment",
+			in:   []byte(`{"r": "1.2.3"}`),
+			out: TestStruct{Release: OperatorRelease{Release: []semver.PRVersion{
+				mustNewPRVersion("1"),
+				mustNewPRVersion("2"),
+				mustNewPRVersion("3"),
+			}}},
+		},
+		{
+			name: "numeric-segments",
+			in:   []byte(`{"r": "20240101.12345"}`),
+			out: TestStruct{Release: OperatorRelease{Release: []semver.PRVersion{
+				mustNewPRVersion("20240101"),
+				mustNewPRVersion("12345"),
+			}}},
+		},
+		{
+			name: "alphanumeric-segments",
+			in:   []byte(`{"r": "alpha.beta.1"}`),
+			out: TestStruct{Release: OperatorRelease{Release: []semver.PRVersion{
+				mustNewPRVersion("alpha"),
+				mustNewPRVersion("beta"),
+				mustNewPRVersion("1"),
+			}}},
+		},
+		{
+			name: "alphanumeric-with-hyphens",
+			in:   []byte(`{"r": "rc-1.build-123"}`),
+			out: TestStruct{Release: OperatorRelease{Release: []semver.PRVersion{
+				mustNewPRVersion("rc-1"),
+				mustNewPRVersion("build-123"),
+			}}},
+		},
+		{
+			name: "mixed-alphanumeric",
+			in:   []byte(`{"r": "1.2-beta.x86-64"}`),
+			out: TestStruct{Release: OperatorRelease{Release: []semver.PRVersion{
+				mustNewPRVersion("1"),
+				mustNewPRVersion("2-beta"),
+				mustNewPRVersion("x86-64"),
+			}}},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			s := TestStruct{}
+			err := json.Unmarshal(tt.in, &s)
+			require.Equal(t, tt.out, s)
+			require.Equal(t, tt.err, err)
+		})
+	}
+}
+
+func mustNewPRVersion(s string) semver.PRVersion {
+	v, err := semver.NewPRVersion(s)
+	if err != nil {
+		panic(err)
+	}
+	return v
+}

pkg/manifests/bundleloader.go

@@ -39,6 +39,7 @@ func (b *bundleLoader) LoadBundle() error {
 
 	errs = append(errs, b.calculateCompressedBundleSize())
 	b.addChannelsFromAnnotationsFile()
+	b.addPackageFromAnnotationsFile()
 
 	if !b.foundCSV {
 		errs = append(errs, fmt.Errorf("unable to find a csv in bundle directory %s", b.dir))
@@ -68,6 +69,14 @@ func (b *bundleLoader) addChannelsFromAnnotationsFile() {
 	}
 }
 
+func (b *bundleLoader) addPackageFromAnnotationsFile() {
+	if b.bundle == nil {
+		// None of this is relevant if the bundle was not found
+		return
+	}
+	b.bundle.Package = b.annotationsFile.Annotations.PackageName
+}
+
 // Compress the bundle to check its size
 func (b *bundleLoader) calculateCompressedBundleSize() error {
 	if b.bundle == nil {

pkg/operators/v1alpha1/clusterserviceversion_types.go

@@ -13,6 +13,7 @@ import (
 	"k8s.io/apimachinery/pkg/labels"
 	"k8s.io/apimachinery/pkg/util/intstr"
 
+	"github.com/operator-framework/api/pkg/lib/release"
 	"github.com/operator-framework/api/pkg/lib/version"
 )
 
@@ -274,8 +275,25 @@ type APIServiceDefinitions struct {
 // that can manage apps for a given version.
 // +k8s:openapi-gen=true
 type ClusterServiceVersionSpec struct {
-	InstallStrategy           NamedInstallStrategy      `json:"install"`
-	Version                   version.OperatorVersion   `json:"version,omitempty"`
+	InstallStrategy NamedInstallStrategy    `json:"install"`
+	Version         version.OperatorVersion `json:"version,omitempty"`
+	// release specifies the packaging version of the operator, defaulting to empty
+	// release is optional
+	//
+	// A ClusterServiceVersion's release field is used to provide a secondary ordering
+	// for operators that share the same semantic version. This is useful for
+	// operators that need to make changes to the CSV which don't affect their functionality,
+	// for example:
+	// - to fix a typo in their description
+	// - to add/amend annotations or labels
+	// - to amend examples or documentation
+	//
+	// It is up to operator authors to determine the semantics of release versions they use
+	// for their operator.  All release versions must conform to the semver prerelease format
+	// (dot-separated identifiers containing only alphanumerics and hyphens) and are limited
+	// to a maximum length of 20 characters.
+	// +optional
+	Release                   release.OperatorRelease   `json:"release,omitzero"`
 	Maturity                  string                    `json:"maturity,omitempty"`
 	CustomResourceDefinitions CustomResourceDefinitions `json:"customresourcedefinitions,omitempty"`
 	APIServiceDefinitions     APIServiceDefinitions     `json:"apiservicedefinitions,omitempty"`
@@ -595,6 +613,7 @@ type ResourceInstance struct {
 // +kubebuilder:subresource:status
 // +kubebuilder:printcolumn:name="Display",type=string,JSONPath=`.spec.displayName`,description="The name of the CSV"
 // +kubebuilder:printcolumn:name="Version",type=string,JSONPath=`.spec.version`,description="The version of the CSV"
+// +kubebuilder:printcolumn:name="Release",type=string,JSONPath=`.spec.release`,description="The release of this version of the CSV"
 // +kubebuilder:printcolumn:name="Replaces",type=string,JSONPath=`.spec.replaces`,description="The name of a CSV that this one replaces"
 // +kubebuilder:printcolumn:name="Phase",type=string,JSONPath=`.status.phase`
 

pkg/validation/internal/bundle.go

@@ -42,9 +42,26 @@ func validateBundle(bundle *manifests.Bundle) (result errors.ManifestResult) {
 	if sizeErrors != nil {
 		result.Add(sizeErrors...)
 	}
+	nameErrors := validateBundleName(bundle)
+	if nameErrors != nil {
+		result.Add(nameErrors...)
+	}
 	return result
 }
 
+func validateBundleName(bundle *manifests.Bundle) []errors.Error {
+	var errs []errors.Error
+	// bundle naming with a specified release version must follow the pattern
+	// <package-name>-v<csv-version>-<release-version>
+	if len(bundle.CSV.Spec.Release.Release) > 0 {
+		expectedName := fmt.Sprintf("%s-v%s-%s", bundle.Package, bundle.CSV.Spec.Version.String(), bundle.CSV.Spec.Release.String())
+		if bundle.Name != expectedName {
+			errs = append(errs, errors.ErrInvalidBundle(fmt.Sprintf("bundle name with release versioning %q does not match expected name %q", bundle.Name, expectedName), bundle.Name))
+		}
+	}
+	return errs
+}
+
 func validateServiceAccounts(bundle *manifests.Bundle) []errors.Error {
 	// get service account names defined in the csv
 	saNamesFromCSV := make(map[string]struct{}, 0)

pkg/validation/internal/typecheck.go

@@ -28,7 +28,7 @@ func checkEmptyFields(result *errors.ManifestResult, v reflect.Value, parentStru
 
 		// Omitted field tags will contain ",omitempty", and ignored tags will
 		// match "-" exactly, respectively.
-		isOptionalField := strings.Contains(tag, ",omitempty") || tag == "-"
+		isOptionalField := strings.Contains(tag, ",omitempty") || strings.Contains(tag, ",omitzero") || tag == "-"
 		emptyVal := fieldValue.IsZero()
 
 		newParentStructName := fieldType.Name