OPRUN-4548: bundle version increased type safety / serialization support

[grokspawn]

Description of the change:
This is a types consolidation between op-reg CompositeVersion and op-con VersionRelease.

api-diff is expected to fail here, and will need to be overridden (since we are un-exporting the fields to make this an opaque type).

There will be an additional PR to more widely adopt the types internally.

Motivation for the change:
Improved safety by declaring a distinct Release type instead of implicitly using blang semver.Version (so this becomes an implementation detail and could be replaced with any type which behaved identically). The original implementation was evaluating the tradeoffs between re-use of the semver.Parse method versus re-implementing just the semver.org pre-release version info for validation.

In order to encourage use of the types as first-class fields in APIs, the types support serialization as JSON objects.
One-way stringification is provided for the VersionRelease type in a manner suitable for use as a metadata.Name in kubernetes.
Round-trip stringification is provided for the Release type.

In order to provide identical type access from outside and inside the system, the types are implemented in the model package (considered an internal package) and re-exported via the declcfg package (which is the intended interface point for external clients).

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

[codecov]

Codecov Report

❌ Patch coverage is 68.42105% with 30 lines in your changes missing coverage. Please review.
✅ Project coverage is 57.76%. Comparing base (21f9b55) to head (0b737df).
⚠️ Report is 5 commits behind head on master.

Files with missing lines	Patch %	Lines
alpha/declcfg/declcfg.go	50.00%	11 Missing and 5 partials ⚠️
alpha/model/versionrelease.go	75.43%	10 Missing and 4 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1938      +/-   ##
==========================================
+ Coverage   57.68%   57.76%   +0.07%     
==========================================
  Files         139      140       +1     
  Lines       13363    13426      +63     
==========================================
+ Hits         7708     7755      +47     
- Misses       4468     4481      +13     
- Partials     1187     1190       +3     

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

[tmshort]

/approve

[tmshort]

/approve
Still approve after change

[openshift-ci]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: tmshort

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

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [tmshort]

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

[grokspawn]

I removed the approval label because there was some fundamental change in this PR and I'd appreciate a re-review, please!

[grokspawn]

rebased the pr to keep it current

[Copilot]

Pull request overview

This PR consolidates bundle version/release handling by introducing a dedicated VersionRelease / Release type in alpha/model and switching template and declcfg logic from the previous composite-version approach to the new API, with added JSON serialization support.

Changes:

• Add model.VersionRelease and model.Release with comparison, parsing, and Kubernetes-safe stringification helpers.
• Replace CompositeVersion() usage with VersionRelease() in declcfg bundle ordering and substitutes template validation.
• Update conversion/tests to use the new release parsing and updated error messages.

Reviewed changes

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

Show a summary per file

File	Description
alpha/template/substitutes/substitutes.go	Switch substitution validation to compare bundles via VersionRelease(); tweak substitution error formatting.
alpha/template/substitutes/substitutes_test.go	Update expected error text for missing version property scenario.
alpha/model/versionrelease.go	Introduce Release + VersionRelease types with parsing/comparison and JSON tags.
alpha/model/versionrelease_test.go	Add unit tests for JSON (un)marshal, round-trip, and NewRelease validation.
alpha/declcfg/declcfg.go	Re-export version types from model; replace CompositeVersion with VersionRelease() logic and legacy build-metadata conversion.
alpha/declcfg/declcfg_to_model.go	Switch release parsing to model.NewRelease and adapt internal assignment.
alpha/declcfg/declcfg_to_model_test.go	Update expected error message for invalid release parsing.

---

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

[Copilot]

Pull request overview

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

---

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

[Copilot]

NewRelease is exported as a mutable var function value, which allows external packages to reassign it (e.g. declcfg.NewRelease = ...) and change declcfg behavior globally. This is a surprising and unsafe API surface; prefer exporting a real wrapper function (e.g. func NewRelease(string) (Release, error)) so callers can’t mutate package behavior.

Suggested change

	var NewRelease = model.NewRelease
	func NewRelease(version string) (Release, error) {
	return model.NewRelease(version)
	}

[openshift-ci-robot]

@grokspawn: This pull request references OPRUN-4548 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:
This is a types consolidation between op-reg CompositeVersion and op-con VersionRelease.

api-diff is expected to fail here, and will need to be overridden (since we are un-exporting the fields to make this an opaque type).

There will be an additional PR to more widely adopt the types internally.

Motivation for the change:
Improved safety by declaring a distinct Release type instead of implicitly using blang semver.Version (so this becomes an implementation detail and could be replaced with any type which behaved identically). The original implementation was evaluating the tradeoffs between re-use of the semver.Parse method versus re-implementing just the semver.org pre-release version info for validation.

In order to encourage use of the types as first-class fields in APIs, the types support serialization as JSON objects.
One-way stringification is provided for the VersionRelease type in a manner suitable for use as a metadata.Name in kubernetes.
Round-trip stringification is provided for the Release type.

In order to provide identical type access from outside and inside the system, the types are implemented in the model package (considered an internal package) and re-exported via the declcfg package (which is the intended interface point for external clients).

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.