From b6e8295289112bb3b980533ce399885891d53da0 Mon Sep 17 00:00:00 2001 From: grokspawn Date: Wed, 21 Jan 2026 16:01:26 -0600 Subject: [PATCH 1/2] add bundle release version attribute, substitutes template Signed-off-by: grokspawn --- .../Concepts/crds/clusterserviceversion.md | 98 +++++ .../en/docs/Reference/catalog-templates.md | 355 +++++++++++++++++- .../en/docs/Reference/file-based-catalogs.md | 185 ++++++++- 3 files changed, 635 insertions(+), 3 deletions(-) diff --git a/content/en/docs/Concepts/crds/clusterserviceversion.md b/content/en/docs/Concepts/crds/clusterserviceversion.md index 6ad9b1a3..29297fad 100644 --- a/content/en/docs/Concepts/crds/clusterserviceversion.md +++ b/content/en/docs/Concepts/crds/clusterserviceversion.md @@ -106,3 +106,101 @@ spec: version: v1alpha1 kind: Other ``` +## Release Field + +The `release` field is an optional field in the CSV spec that specifies the packaging version of an operator. It allows operator authors to distinguish between different builds of the same operator version. + +### When to Use the Release Field + +Use the `release` field when you need to make changes to the CSV that don't affect the operator's functionality: + +- Fixing typos in descriptions +- Adding or amending annotations or labels +- Amending examples or documentation +- Producing different builds for different environments + +### Format and Validation + +The `release` field must conform to the [semver prerelease format](https://semver.org/spec/v2.0.0.html#spec-item-9): +- Dot-separated identifiers containing only alphanumerics and hyphens +- Maximum length of 20 characters +- **Cannot contain build metadata** (the `+` character and everything after it) +- Examples: `1`, `alpha`, `alpha.1`, `beta-1`, `rc.2.0` + +### Example + +```yaml +apiVersion: operators.coreos.com/v1alpha1 +kind: ClusterServiceVersion +metadata: + name: memcached-operator-v0.10.0-1 +spec: + version: 0.10.0 + release: "1" # Optional packaging version + displayName: Memcached Operator + description: This is an operator for memcached. + # ... rest of CSV spec +``` + +### Bundle Naming Convention with Release + +When a `release` field is specified, the bundle name must follow the convention: + +``` +-v- +``` + +**Examples:** +- `memcached-operator-v0.10.0-1` +- `memcached-operator-v0.10.0-alpha.1` +- `memcached-operator-v0.10.0-rc.2` + +### Version Ordering + +Bundles are ordered using a composite version that considers both `version` and `release`: + +1. Bundles are first ordered by semantic version +2. For bundles with the same version, those **with** a release are ordered **before** those **without** a release +3. Bundles with the same version and both having releases are ordered by their release version + +```mermaid +graph TD + A[Bundle Comparison] --> B{Same Version?} + B -->|No| C[Order by Version] + B -->|Yes| D{Both have Release?} + D -->|No| E{Has Release?} + D -->|Yes| F[Order by decreasing Release] + E -->|Bundle A| G[A before B] + E -->|Bundle B| H[B before A] + + style A fill:#e1f5ff + style C fill:#c3e6cb + style F fill:#c3e6cb + style G fill:#c3e6cb + style H fill:#c3e6cb +``` + +**Example ordering:** +``` +memcached-operator.v0.9.0 # version 0.9.0, no release +memcached-operator-v0.10.0-alpha # version 0.10.0, release "alpha" +memcached-operator-v0.10.0-2 # version 0.10.0, release "2" +memcached-operator-v0.10.0-1 # version 0.10.0, release "1" +memcached-operator.v0.10.0 # version 0.10.0, no release +``` + +### Build Metadata Restriction + +The `release` field **cannot contain build metadata**. The following is **invalid**: + +```yaml +# ❌ INVALID - release cannot contain build metadata (the + character) +version: 0.10.0 +release: "1+fffdb0e" +``` + +```yaml +# ✅ VALID - build metadata can be in version when no release is present +version: 0.10.0+fffdb0e +# no release field +``` \ No newline at end of file diff --git a/content/en/docs/Reference/catalog-templates.md b/content/en/docs/Reference/catalog-templates.md index ad3b4c13..21df2640 100644 --- a/content/en/docs/Reference/catalog-templates.md +++ b/content/en/docs/Reference/catalog-templates.md @@ -141,7 +141,7 @@ opm alpha convert-template basic [flags] -Example template in JSON format after the conversion: +### Example template in JSON format after the conversion ```json { @@ -171,6 +171,61 @@ Example template in JSON format after the conversion: } ``` +## Using existing FBC to bootstrap a Substitutes Template +The `opm` tool provides the capability to generate a substitutes template from existing FBC in JSON or YAML formats. + +### Usage + +```sh +./bin/opm alpha convert-template substitutes [flags] +``` + +| Flag | Description | +| ------------------- | -------------------------------------------------------------------------------------- | +| -h, --help | prints help/usage information | +| -o, --output | the output format, can be `yaml` or `json` | +| --skip-tls-verify | skip TLS certificate verification for container image registries while pulling bundles | +| --use-http | use plain HTTP for container image registries while pulling bundles | + +`--skip-tls-verify` and `--use-http` are mutually exclusive flags. + +### Example template in JSON format after the conversion +>Note: empty substitutions are provided, but must be filled in to be valid + +```json +{ + "schema": "olm.template.substitutes", + "entries": [ + { + "schema": "olm.package", + "name": "hello-kubernetes", + "defaultChannel": "alpha", + "description": "hello-kubernetes" + }, + { + "schema": "olm.channel", + "name": "alpha", + "package": "hello-kubernetes", + "entries": [ + { + "name": "hello-kubernetes.v0.0.1" + } + ] + }, + { + "schema": "olm.bundle", + "image": "docker.io/test/hello-kubernetes-operator-bundle:v0.0.1" + } + ], + "substitutions": [ + { + "name":, + "base": + } + ] +} +``` + ## Semver Template Since a `catalog template` is identified as an input schema which is processed to generate a valid FBC, we can define a `semver template` as a schema which uses channel conventions to facilitate the auto-generation of channels adhering to [Semantic Versioning](https://semver.org/) (semver) guidelines and consistent with best practices on [channel naming](/docs/best-practices/channel-naming/#naming). This approach may be attractive to operator authors who are defining a new upgrade graph, or are already close enough to this template's conventions to be able to adopt it. @@ -511,3 +566,301 @@ package: testoperator schema: olm.channel ``` +## Substitutes Template + +The substitutes template provides a safe and structured way to replace bundles in an upgrade graph with newer packaging versions. This is particularly useful when you need to republish a bundle with non-functional changes (documentation fixes, label updates, etc.) and want to ensure users upgrade to the new bundle. + +#### Problem Statement + +Before the substitutes template, when you needed to replace a bundle in a catalog (for example, `foo.v1.0.0` with a documentation fix), you had two options: + +1. **Manually edit all channel entries** - Error-prone and requires updating multiple references +2. **Use the deprecated `substitutesFor` CSV field** - Not available in file-based catalogs + +The `olm.template.substitutes` template solves this by automatically handling the complex graph mutations required to safely replace bundles. + +### Schema + +```yaml +schema: olm.template.substitutes +entries: + - # Existing FBC catalog content (packages, channels, bundles) +substitutions: + - name: # Bundle image to substitute + base: # Bundle name to replace +``` + +### How It Works + +When you define a substitution: + +1. The template validates that the substitute bundle has a higher composite version than the base bundle +2. For each channel containing the base bundle, the template: + - Adds the new bundle to the channel + - Move upgrade edges (replaces, skips, skipRange) from the base to the substitute + - Adds a skip edge from substitute to base + - Updates all other entries that reference the base to reference the substitute instead + +Before Substitution +```mermaid +graph LR + A1[foo.v0.9.0] -->|replace| B1[foo.v1.0.0] + B1 -->|replace| C1[foo.v1.1.0] +``` + +After Substitution +```mermaid +graph LR + A2[foo.v0.9.0] -->|replace| B2[foo-v1.0.0-1
NEW] + B2 -->|replace| C2[foo.v1.1.0] + B2 -.->|skip| D2[foo.v1.0.0
OLD] + + style B2 fill:#c3e6cb,stroke:#28a745,stroke-width:3px + style D2 fill:#f8d7da,stroke:#dc3545,stroke-width:2px,stroke-dasharray: 5 5 +``` + +### Step-by-Step Example + +#### Step 1: Initial Catalog State + +You have a catalog with three bundles in the `stable` channel: + +```yaml +--- +schema: olm.channel +package: foo +name: stable +entries: + - name: foo.v0.9.0 + - name: foo.v1.0.0 + replaces: foo.v0.9.0 + - name: foo.v1.1.0 + replaces: foo.v1.0.0 +--- +schema: olm.bundle +package: foo +name: foo.v1.0.0 +image: quay.io/example/foo-bundle:v1.0.0 +properties: + - type: olm.package + value: + packageName: foo + version: 1.0.0 +``` + +#### Step 2: Create New Bundle with Release + +You discover `foo.v1.0.0` is missing a critical annotation. +You +1. update the bundle's annotation in `metadata/annotations.yaml` +2. update the bundle's CSV with `spec.release` set (here set to 1) +3. ensure that the bundle's `metadata-name` follows the format required for using release versions +4. publish the bundle + +The `opm render`-ed bundle image would look something like this in FBC: + +```yaml +--- +schema: olm.bundle +package: foo +name: foo-v1.0.0-1 # New name with release +image: quay.io/example/foo-bundle:v1.0.0-1 +properties: + - type: olm.package + value: + packageName: foo + version: 1.0.0 + release: "1" # Added release +``` + +#### Step 3: Create Substitutes Template +Instead of manually updating the catalog, create a substitutes template: +> Note: see [Using existing FBC to bootstrap a Substitutes Template](#using-existing-fbc-to-bootstrap-a-substitutes-template) to get `opm` to generate this for you. + +```yaml +schema: olm.template.substitutes +entries: + # Include all your existing catalog content here + # (packages, channels, bundles - except the new foo-v1.0.0-1) +substitutions: + - name: quay.io/example/foo-bundle:v1.0.0-1 # New bundle image + base: foo.v1.0.0 # Old bundle name to replace +``` + +#### Step 4: Render the Template + +Use `opm` to render the template: + +```bash +opm alpha render-template substitutes-template.yaml -o yaml > catalog/foo/index.yaml +``` + +The rendered catalog will have: + +```yaml +--- +schema: olm.channel +package: foo +name: stable +entries: + - name: foo.v0.9.0 + - name: foo-v1.0.0-1 # NEW substitute bundle + replaces: foo.v0.9.0 + skips: + - foo.v1.0.0 # Skips the old bundle + - name: foo.v1.1.0 + replaces: foo-v1.0.0-1 # Updated to point to new bundle + - name: foo.v1.0.0 # OLD bundle remains in catalog + # No upgrade edges (orphaned) +``` + +### Substitution Rules and Validation + +The template enforces several validation rules: + +1. **Composite version check**: The substitute bundle must have a higher composite version than the base bundle + ```yaml + # ✅ VALID - release "1" > no release + base: foo.v1.0.0 (version 1.0.0, no release) + name: foo-v1.0.0-1 (version 1.0.0, release "1") + + # ❌ INVALID - same version and release + base: foo-v1.0.0-1 + name: foo-v1.0.0-1 + + # ❌ INVALID - lower composite version + base: foo-v1.0.0-2 + name: foo-v1.0.0-1 + ``` + +2. **Base bundle must exist**: The base bundle name must be present in the catalog + +3. **Required fields**: Both `name` (bundle image) and `base` (bundle name) are required + +4. **Name vs Base validation**: The `name` and `base` cannot be the same + +#### Multiple Substitutions + +You can define multiple substitutions in a single template: + +```yaml +schema: olm.template.substitutes +entries: + # ... catalog content ... +substitutions: + - name: quay.io/example/foo-bundle:v1.0.0-1 + base: foo.v1.0.0 + - name: quay.io/example/foo-bundle:v1.1.0-1 + base: foo.v1.1.0 + - name: quay.io/example/bar-bundle:v2.0.0-alpha.2 + base: bar-v2.0.0-alpha.1 +``` + +The substitutions are processed in order, and each substitution validates against the current state of the catalog. + +#### Upgrade Path Diagram + +```mermaid +stateDiagram-v2 + [*] --> InstalledOld: User has foo.v1.0.0 + [*] --> InstalledNew: New user installs + + InstalledOld --> UpgradeToSubstitute: Catalog updated with
substitution + InstalledNew --> UseSubstitute: Directly installs
foo-v1.0.0-1 + + UpgradeToSubstitute --> foo_v1_0_0_1: OLM sees substitute
skips old bundle + UseSubstitute --> foo_v1_0_0_1: Gets latest bundle + + foo_v1_0_0_1 --> [*]: Up to date + + note right of UpgradeToSubstitute + Skip relationship ensures + users upgrade to the new + packaging version + end note +``` + +### Best Practices + +1. **Use for packaging changes only**: The substitute bundle should be functionally equivalent to the base bundle + +2. **Validate composite versions**: Ensure your substitute bundle has a higher composite version (typically by adding a release field) + +3. **Test before deploying**: Use `opm validate` to verify the rendered catalog: + ```bash + opm alpha render-template template.yaml | opm validate - + ``` + +4. **Keep base bundles**: The old bundle remains in the catalog but becomes unreachable through normal upgrade paths (it's still accessible for historical reference) + +5. **Document substitutions**: Add comments in your template explaining why each substitution was made + + ```yaml + substitutions: + # Fixed typo in operator description + - name: quay.io/example/foo-bundle:v1.0.0-1 + base: foo.v1.0.0 + ``` + +### Complete Working Example + +```yaml +--- +schema: olm.template.substitutes + +# Your existing catalog content +entries: + - schema: olm.package + name: foo + defaultChannel: stable + + - schema: olm.channel + package: foo + name: stable + entries: + - name: foo.v0.9.0 + - name: foo.v1.0.0 + replaces: foo.v0.9.0 + - name: foo.v1.1.0 + replaces: foo.v1.0.0 + + - schema: olm.bundle + package: foo + name: foo.v0.9.0 + image: quay.io/example/foo-bundle:v0.9.0 + properties: + - type: olm.package + value: + packageName: foo + version: 0.9.0 + + - schema: olm.bundle + package: foo + name: foo.v1.0.0 + image: quay.io/example/foo-bundle:v1.0.0 + properties: + - type: olm.package + value: + packageName: foo + version: 1.0.0 + + - schema: olm.bundle + package: foo + name: foo.v1.1.0 + image: quay.io/example/foo-bundle:v1.1.0 + properties: + - type: olm.package + value: + packageName: foo + version: 1.1.0 + +# Define the substitution +substitutions: + - name: quay.io/example/foo-bundle:v1.0.0-1 # New bundle with fixed docs + base: foo.v1.0.0 # Old bundle to replace +``` + +Render with: +```bash +opm alpha render-template substitutes-template.yaml -o yaml > catalog/foo/index.yaml +``` diff --git a/content/en/docs/Reference/file-based-catalogs.md b/content/en/docs/Reference/file-based-catalogs.md index 458ad57f..1fcf4617 100644 --- a/content/en/docs/Reference/file-based-catalogs.md +++ b/content/en/docs/Reference/file-based-catalogs.md @@ -356,8 +356,8 @@ OLM defines a handful of property types, again using the reserved `olm.*` prefix #### `olm.package` An `olm.package` property defines the package name and version. This is a required property on bundles, and there must -be exactly one of these properties. The `packageName` must match the bundle's first-class `package` field, and the -`version` must be a valid [semantic version][semver] +be exactly one of these properties. The `packageName` must match the bundle's first-class `package` field, the +`version` must be a valid [semantic version][semver], and it may include an optional `release` bundle packaging identifier. See the [Bundle Release Property](#bundle_release_property) section for additional format requirements and examples. The `olm.package` property [cue][cuelang-spec] schema is: ```cue @@ -366,6 +366,7 @@ The `olm.package` property [cue][cuelang-spec] schema is: value: { packageName: string & !="" version: string & !="" + release?: string & !="" // optional release version } } ``` @@ -640,6 +641,186 @@ The `olm.bundle.object` property [cue][cuelang-spec] schema is: [semver]: https://semver.org/spec/v2.0.0.html [semver-range]: https://github.com/blang/semver/blob/master/README.md#ranges +### Bundle Release Property + +#### `olm.package` with Release Version + +The `olm.package` property has been extended to support an optional `release` field that specifies the packaging version of a bundle. This allows catalog maintainers to distinguish between different builds of the same operator version. +###### Use Cases for Bundle Release + +Use the `release` field when you need to: + +1. **Republish a bundle with documentation fixes** + ```yaml + # Original bundle + name: foo.v0.3.0 + version: 0.3.0 + # (no release) + + # Updated bundle with fixed description + name: foo-v0.3.0-1 + version: 0.3.0 + release: "1" + ``` + +2. **Create environment-specific builds** + ```yaml + # Production build + name: foo-v0.3.0-prod + version: 0.3.0 + release: "prod" + + # Staging build + name: foo-v0.3.0-staging + version: 0.3.0 + release: "staging" + ``` + +3. **Version catalog packaging changes** + ```yaml + # First packaging iteration + name: foo-v0.3.0-1 + version: 0.3.0 + release: "1" + + # Second iteration with label updates + name: foo-v0.3.0-2 + version: 0.3.0 + release: "2" + ``` + +#### Required Bundle Naming with Release + +When the `release` field is present in the `olm.package` property, the bundle name **must** follow this convention: + +``` +-v- +``` + +`opm validate` will fail if the bundle name doesn't match this normalized format. + +**Valid Examples:** +```yaml +# Release is a number +name: foo-v0.3.0-1 +properties: +- type: olm.package + value: + packageName: foo + version: 0.3.0 + release: "1" + +# Release is alphanumeric +name: foo-v0.3.0-alpha.1 +properties: +- type: olm.package + value: + packageName: foo + version: 0.3.0 + release: "alpha.1" +``` + +**Invalid Example:** +```yaml +# ❌ INVALID - name uses dots instead of hyphens +name: foo.v0.3.0.1 +properties: +- type: olm.package + value: + packageName: foo + version: 0.3.0 + release: "1" +``` + +#### Release Format Constraints + +The `release` field: +- Must conform to semver prerelease format (alphanumerics and hyphens, dot-separated) +- **Cannot contain build metadata** (no `+` character) +- Has a maximum length of 20 characters + +**Invalid release values:** +```yaml +# ❌ INVALID - contains build metadata +release: "1+fffdb0e" + +# ❌ INVALID - contains invalid characters +release: "1_beta" +``` + + +#### Example Bundle with Release + +```yaml +schema: olm.bundle +package: foo +name: foo-v0.3.0-1 # Note: name includes release in format -v- + +image: quay.io/example-com/foo-bundle:v0.3.0-1 +properties: +- type: olm.package + value: + packageName: foo + version: 0.3.0 + release: "1" # Optional packaging version +- type: olm.gvk + value: + group: example.com + version: v1alpha1 + kind: Foo +``` + +#### Composite Version Ordering + +Bundles are compared using a **composite version** that combines the `version` and `release`: + +```mermaid +flowchart LR + A[Bundle A] --> AV[version: 0.3.0
release: 1] + B[Bundle B] --> BV[version: 0.3.0
release: 2] + + AV --> C{Compare Versions} + BV --> C + + C -->|Equal| D{Both have
release?} + C -->|Not Equal| E[Order by version] + + D -->|Yes| F[Order by release] + D -->|No| G{Which has
release?} + + G -->|A| H[B before A] + G -->|B| I[A before B] + + F --> J[Bundle A < Bundle B
1 < 2] + + style C fill:#e1f5ff + style D fill:#e1f5ff + style G fill:#e1f5ff + style F fill:#c3e6cb + style E fill:#c3e6cb + style H fill:#c3e6cb + style I fill:#c3e6cb + style J fill:#c3e6cb +``` + +**Ordering rules:** +1. Compare by version first (using semver comparison) +2. If versions are equal: + - Bundles **with** a release come **before** bundles **without** a release + - Bundles both having releases are ordered by their release version (using semver prerelease comparison) + +**Example ordering sequence:** +``` +foo.v0.2.0 # v0.2.0, no release +foo-v0.3.0-2 # v0.3.0, release "2" +foo-v0.3.0-1 # v0.3.0, release "1" +foo-v0.3.0-beta.1 # v0.3.0, release "beta.1" +foo-v0.3.0-alpha # v0.3.0, release "alpha" (beta > alpha lexicographically) +foo.v0.3.0 # v0.3.0, no release +foo.v0.4.0 # v0.4.0, no release +``` + + ## CLI |No| C[Order by Version] B -->|Yes| D{Both have Release?} D -->|No| E{Has Release?} - D -->|Yes| F[Order by decreasing Release] + D -->|Yes| F[Order by Release] E -->|Bundle A| G[A before B] E -->|Bundle B| H[B before A] @@ -180,13 +181,13 @@ graph TD style H fill:#c3e6cb ``` -**Example ordering:** +**Example versions in ascending order:** ``` memcached-operator.v0.9.0 # version 0.9.0, no release -memcached-operator-v0.10.0-alpha # version 0.10.0, release "alpha" -memcached-operator-v0.10.0-2 # version 0.10.0, release "2" -memcached-operator-v0.10.0-1 # version 0.10.0, release "1" memcached-operator.v0.10.0 # version 0.10.0, no release +memcached-operator-v0.10.0-1 # version 0.10.0, release "1" +memcached-operator-v0.10.0-2 # version 0.10.0, release "2" +memcached-operator-v0.10.0-alpha # version 0.10.0, release "alpha" ``` ### Build Metadata Restriction diff --git a/content/en/docs/Reference/catalog-templates.md b/content/en/docs/Reference/catalog-templates.md index 21df2640..5a430140 100644 --- a/content/en/docs/Reference/catalog-templates.md +++ b/content/en/docs/Reference/catalog-templates.md @@ -219,8 +219,8 @@ The `opm` tool provides the capability to generate a substitutes template from e ], "substitutions": [ { - "name":, - "base": + "name": "", + "base": "" } ] } @@ -568,9 +568,7 @@ schema: olm.channel ## Substitutes Template -The substitutes template provides a safe and structured way to replace bundles in an upgrade graph with newer packaging versions. This is particularly useful when you need to republish a bundle with non-functional changes (documentation fixes, label updates, etc.) and want to ensure users upgrade to the new bundle. - -#### Problem Statement +The substitutes template provides a safe and structured way to replace bundles in an upgrade graph with newer packaging versions. This is particularly useful when you need to republish a bundle with non-functional changes (documentation fixes, label updates, etc.) and want to ensure users can upgrade to the new bundle. Before the substitutes template, when you needed to replace a bundle in a catalog (for example, `foo.v1.0.0` with a documentation fix), you had two options: @@ -597,7 +595,7 @@ When you define a substitution: 1. The template validates that the substitute bundle has a higher composite version than the base bundle 2. For each channel containing the base bundle, the template: - Adds the new bundle to the channel - - Move upgrade edges (replaces, skips, skipRange) from the base to the substitute + - Moves upgrade edges (replaces, skips, skipRange) from the base to the substitute - Adds a skip edge from substitute to base - Updates all other entries that reference the base to reference the substitute instead @@ -651,7 +649,7 @@ properties: #### Step 2: Create New Bundle with Release You discover `foo.v1.0.0` is missing a critical annotation. -You +You: 1. update the bundle's annotation in `metadata/annotations.yaml` 2. update the bundle's CSV with `spec.release` set (here set to 1) 3. ensure that the bundle's `metadata-name` follows the format required for using release versions diff --git a/content/en/docs/Reference/file-based-catalogs.md b/content/en/docs/Reference/file-based-catalogs.md index 1fcf4617..1293fc12 100644 --- a/content/en/docs/Reference/file-based-catalogs.md +++ b/content/en/docs/Reference/file-based-catalogs.md @@ -357,7 +357,7 @@ OLM defines a handful of property types, again using the reserved `olm.*` prefix An `olm.package` property defines the package name and version. This is a required property on bundles, and there must be exactly one of these properties. The `packageName` must match the bundle's first-class `package` field, the -`version` must be a valid [semantic version][semver], and it may include an optional `release` bundle packaging identifier. See the [Bundle Release Property](#bundle_release_property) section for additional format requirements and examples. +`version` must be a valid [semantic version][semver], and the package may include an optional `release` bundle packaging field. See the [Bundle Release Property](#bundle-release-property) section for additional format requirements and examples. The `olm.package` property [cue][cuelang-spec] schema is: ```cue @@ -646,7 +646,7 @@ The `olm.bundle.object` property [cue][cuelang-spec] schema is: #### `olm.package` with Release Version The `olm.package` property has been extended to support an optional `release` field that specifies the packaging version of a bundle. This allows catalog maintainers to distinguish between different builds of the same operator version. -###### Use Cases for Bundle Release +##### Use Cases for Bundle Release Use the `release` field when you need to: @@ -788,8 +788,8 @@ flowchart LR D -->|Yes| F[Order by release] D -->|No| G{Which has
release?} - G -->|A| H[B before A] - G -->|B| I[A before B] + G -->|A| H[B < A] + G -->|B| I[A < B] F --> J[Bundle A < Bundle B
1 < 2] @@ -806,17 +806,17 @@ flowchart LR **Ordering rules:** 1. Compare by version first (using semver comparison) 2. If versions are equal: - - Bundles **with** a release come **before** bundles **without** a release + - Bundles **with** a release are **greater than** bundles **without** a release - Bundles both having releases are ordered by their release version (using semver prerelease comparison) -**Example ordering sequence:** +**Example ascending order sequence:** ``` foo.v0.2.0 # v0.2.0, no release -foo-v0.3.0-2 # v0.3.0, release "2" -foo-v0.3.0-1 # v0.3.0, release "1" -foo-v0.3.0-beta.1 # v0.3.0, release "beta.1" -foo-v0.3.0-alpha # v0.3.0, release "alpha" (beta > alpha lexicographically) foo.v0.3.0 # v0.3.0, no release +foo-v0.3.0-1 # v0.3.0, release "1" is greater than no release +foo-v0.3.0-2 # v0.3.0, release "2" is greater than release "1" +foo-v0.3.0-alpha # v0.3.0, release "alpha" is greater than release "2" +foo-v0.3.0-beta.1 # v0.3.0, release "beta.1" is greater than release "alpha" foo.v0.4.0 # v0.4.0, no release ```