add bundle release version attribute, substitutes template

[grokspawn]

With merge of operator-framework/api#454 (for CSV) and operator-framework/operator-registry#1792 (for FBC and substitutes template support), we have new capabilities to express the concept of a packaging-only revision of an operator.

Expressed in the ClusterServiceVersion as an optional release field, captured in the olm.bundle FBC schema version property olm.package and leveraged in the new substitutes template type, this attribute opens up a new axis in bundle operator versioning.

This release version allows migration to the new version on clusters with the old version installed, and facilitates graph updates to prefer the new release version over previous versions.

Contributions:

• release version in CSV
• mentioning the new field in FBC bundle properties
• use and requirements of the new field in FBC
• how to generate a new Substitutes catalog template from existing FBC
• the Substitutes catalog template anatomy, use, and restrictions

I used claude to help generate some diagrams and examples, but I'm to blame for any mistakes.

[Copilot]

Pull request overview

This PR adds comprehensive documentation for a new bundle release version attribute that enables packaging-only revisions of operators. The feature introduces an optional release field for ClusterServiceVersions and file-based catalog bundles, along with a new substitutes template for managing bundle replacements.

Changes:

• Extended olm.package property schema to support optional release field with format constraints and validation rules
• Documented new substitutes template (olm.template.substitutes) for safely replacing bundles with packaging revisions
• Added release field documentation to ClusterServiceVersion spec with naming conventions and version ordering rules

Reviewed changes

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

File	Description
content/en/docs/Reference/file-based-catalogs.md	Adds Bundle Release Property section documenting the optional release field in olm.package, including use cases, naming conventions, format constraints, and composite version ordering
content/en/docs/Reference/catalog-templates.md	Documents the new substitutes template for replacing bundles, including schema, workflow diagrams, validation rules, and complete working examples
content/en/docs/Concepts/crds/clusterserviceversion.md	Adds Release Field section to CSV documentation with format validation, naming conventions, and version ordering behavior

---

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

[grokspawn]

lint is failing due to the number of links being evaluated. This passes locally, and hopefully #343 will help this for future updates.

[trgeiger]

Couple nits

[rashmigottipati]

Looks good to me overall.

Can we add a brief note on backward compatibility that explicitly describes the behavior when the release field is not present? Even though the field is optional, it would be helpful to clarify how bundles without release are handled (ordering, comparison, and so on) to set correct expectations for mixed catalogs.

[tmshort]

Is this ordering correct with respect to rule #2 above?

2. For bundles with the same version, those with a release are ordered before those without a release