From 63e7c79890f63d60d11fb85a6b6434d33edb9ce9 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 10 Aug 2026 23:17:04 -0700 Subject: [PATCH 01/18] docs(rfc): define stable release policy Signed-off-by: Drew Newberry --- rfc/0014-release-stability/README.md | 266 ++++++++++++++++++ rfc/0014-release-stability/build-matrix.md | 70 +++++ .../release-qualification.md | 118 ++++++++ 3 files changed, 454 insertions(+) create mode 100644 rfc/0014-release-stability/README.md create mode 100644 rfc/0014-release-stability/build-matrix.md create mode 100644 rfc/0014-release-stability/release-qualification.md diff --git a/rfc/0014-release-stability/README.md b/rfc/0014-release-stability/README.md new file mode 100644 index 0000000000..4a2f9b41f7 --- /dev/null +++ b/rfc/0014-release-stability/README.md @@ -0,0 +1,266 @@ +--- +authors: + - "@anewberry" +state: review +links: + - https://github.com/NVIDIA/OpenShell/pull/2148 +--- + +# RFC 0014 - Alpha Exit Criteria and Stable Release Policy + +## Summary + +The goal of this RFC is to define OpenShell's exit from alpha and establish a +predictable release cycle for production users and ecosystem developers. +It defines release qualification requirements, compatibility guidelines for +stable and evolving APIs, per-commit development releases, nightly builds, and +weekly stable releases. + +## Motivation + +OpenShell's alpha process supports rapid iteration but does not define which +artifacts qualify for release, which interfaces users can rely on, or how long +release lines are maintained. OpenShell 0.1.0 is considered suitable for +production use within the published support matrix. This suitability means +that supported platform, architecture, installation method, compute driver, +deployment topology, and capability combinations have passed the required +conformance and upgrade qualification; stable interfaces have an established +compatibility baseline; supported upgrade and rollback paths have been tested; +release artifacts have verified provenance, SBOMs, and digests; and required +security review has found no unresolved blocking issues. Experimental and +unsupported combinations remain clearly identified and are not covered by the +production support promise. + +## Proposal + +### Release cadence + +Starting with 0.1.0, OpenShell documents each release by its version, support +status, and the maturity of individual capabilities. + +OpenShell publishes stable tagged releases intended for production use within +the published support matrix. Stable releases occur every Tuesday and increment +the patch version, for example `0.1.1` followed by `0.1.2`. A stable tag is +published only when there are changes and every blocking qualification suite +passes. + +OpenShell publishes a development release for every commit to `main`. Each +development release identifies its source commit and artifact manifest, and the +floating `dev` alias points to the newest one. Development releases enable all +development compilation flags and features. They are not qualification +evidence, are not supported deployment pins, and are not candidates for stable +promotion. + +OpenShell also publishes nightly prereleases of the next expected patch +release. After `0.1.1`, a nightly release may be identified as +`0.1.2-nightly.20260811.1`, where the final component distinguishes multiple +candidates created on the same date. Git tags add the normal `v` prefix. Each +nightly identifies one source commit and one artifact manifest. A floating +`nightly` alias may point to the newest candidate for convenience, but the alias +is not qualification evidence and is not a supported deployment pin. + +Release tooling maps development and nightly versions into the syntax and +ordering rules required by Python, Cargo, Debian, RPM, Snap, OCI, Helm, and +other publication targets. The mapping must preserve the invariant that these +releases sort before their corresponding stable release wherever the package +ecosystem supports prerelease ordering. + +### Project version and compatibility contract + +Version 0.1.0 begins OpenShell's supported compatibility contract. For +the 0.x series: + +- Patch releases may contain bug fixes and additive, backward-compatible + functionality. They do not intentionally break a stable interface. +- An unavoidable breaking change to any stable interface starts a new minor + release and resets the patch version, for example `0.1.x` to `0.2.0`. +- Security fixes may make the narrowest necessary incompatible change when no + safe compatible remediation exists. The release notes and security guidance + must describe the operator action without exposing embargoed information. +- Deprecation is preferred to removal. Except for urgent security or safety + reasons, a deprecated stable interface remains available for the rest of its + minor release line and is removed only in a later minor release. + +The project version covers more than protobuf wire compatibility. Before +0.1.0, OpenShell publishes an inventory that classifies at least these surfaces: + +| Surface | Stable promise when designated stable | +| --- | --- | +| Protobuf and generated SDK APIs | Source, wire, JSON, and documented semantic compatibility | +| Hand-written SDK APIs | Documented public types, methods, and behavior remain compatible | +| CLI | Documented commands, flags, exit behavior, and machine-readable output remain compatible | +| Gateway configuration | Existing supported configuration continues to parse with equivalent semantics | +| Sandbox policy schema | Existing supported policies continue to validate and enforce equivalent intent | +| Helm and installation configuration | Supported values, environment variables, and upgrade paths remain compatible | +| Extension contracts | Stable driver, interceptor, and middleware contracts evolve additively | +| Persisted operational state | Supported upgrades migrate state without requiring a clean installation | + +The 0.1.0 schemas, SDK signatures, CLI contract fixtures, configuration and +policy schemas, and upgrade fixtures become the initial compatibility baseline. +Every later stable release records which baseline it was checked against. + +### Capability maturity and release availability + +Capability maturity is independent from the release that contains it: + +| Maturity | API naming | Compatibility | +| --- | --- | --- | +| Stable | Stable protobuf packages such as `v1` or `v2` | Covered by the release compatibility contract | +| Experimental | Explicit unstable package such as `v1beta1` | May change with documented migration guidance | + +Stable and experimental capabilities may be included in stable, nightly, or +development artifacts according to the release configuration. Availability +only in a development or nightly build is not a third maturity level and does +not make the capability experimental. The capability must still be classified +independently as stable or experimental. A capability absent from stable +artifacts has no stable release availability or support promise. + +A new API that is useful to release but whose design is still evolving starts +with a package such as `v1beta1`. It may evolve to `v1beta2` in a patch release +because the package name advertises the lack of stable compatibility. Release +notes still explain the change and any migration path. Graduation creates a +stable `v1` package; it does not rename the experimental package in place. + +Features that are not ready to be released are protected by named compile-time +features such as `unstable-` and collected under a `dev` feature. +Development releases are built with all development compilation flags and +features enabled. Stable tagged releases and nightlies build service binaries, +CLI commands, configuration fields, and documentation without those features. +For now, SDK packages may include the generated types and client methods for +development capabilities in every release so the project does not need to +publish separate development and release SDK variants. Their presence in an SDK +does not make the capability available or supported: the target service must +advertise and implement it, and only stable SDK interfaces are covered by the +compatibility contract. CI for every commit to `main` builds and tests both the +development feature set and the release feature set so compile-gated +development cannot silently break supported builds. + +### Breaking changes and API versioning + +A project release version bump and a protocol package revision solve different +problems and are applied together when appropriate. + +If a breaking change affects a stable OpenShell surface, the release moves to +the next minor version. If the same change is incompatible with a stable +protobuf contract, the protocol also moves to a new major-versioned package, +for example `openshell.v1` to `openshell.v2`. The supported server retains the +old protocol for the maintenance window or supplies an explicit migration path; +the package revision does not by itself satisfy the project-level versioning +requirement. + +A breaking CLI, SDK, configuration, policy, Helm, or state change still requires +a minor project release even when no protobuf package changes. Conversely, a +new experimental `v1beta2` package does not require a minor project release +when it does not break any stable interface. + +Breaking-change detection runs during code review and again during nightly +qualification. Stable protobuf packages use Buf's `FILE` rules against the +latest stable baseline and any additional supported baseline needed for the +N-1 maintenance promise. Language-specific API checks or agent review skills +cover the public SDKs. +Contract fixtures cover CLI, configuration, policy, and Helm surfaces. Upgrade +and version-skew tests cover semantic and persisted-state behavior that a schema +diff cannot detect. + +### Nightly qualification and stable release promotion + +The release system separates candidate creation, qualification, and stable +publication: + +```mermaid +flowchart LR + A["Commit to main"] --> B["Dev release
dev features enabled"] + A --> C["Qualified main commit"] + C --> D["Nightly candidate
release feature set"] + D --> E["Nightly qualification"] + E -->|"pass"| F["Eligible Tuesday candidate"] + E -->|"fail"| G["No stable release"] + F --> H["Build or promote stable artifacts"] + H --> I["Final artifact checks"] + I -->|"pass"| J["Create tag and publish"] + I -->|"fail"| G +``` + +Every nightly candidate produces a manifest containing its canonical version, +full source commit, build inputs, artifact names and digests, SBOM and provenance +references, and qualification results. Qualification installs and exercises the +candidate artifacts wherever practical rather than substituting a source build. + +Release qualification consists of four suites defined in the +[release qualification supplement](release-qualification.md): + +- **Conformance** runs across supported driver and gateway configurations. It + verifies core sandbox behavior, policy enforcement, and extension contracts. +- **Upgrade** runs once per supported installation package and verifies its + upgrade path, state migration, post-upgrade health, and rollback where + promised. +- **Breaking API change review** runs once per candidate and compares stable + protobuf and SDK interfaces with every applicable compatibility baseline. +- **Security review** runs once per candidate and verifies security scan + results, reviews changes to security-sensitive boundaries, and confirms that + every finding has the required disposition. + +The initial release targets are defined in the [build matrix](build-matrix.md), +and blocking coverage is defined in the +[release qualification supplement](release-qualification.md). + +The weekly release selects the newest eligible nightly candidate published +before a documented cutoff. No source change is allowed between candidate +qualification and stable publication. The candidate build produces canonical +binary payloads once; standalone downloads, OCI images, and installation +packages use those same payloads. Content-addressable artifacts such as OCI +images are promoted by digest rather than rebuilt. Package formats whose +metadata embeds the release version may rebuild only the package envelope. They +must not recompile executables or libraries, and the packaged payload digests +must match the candidate manifest. Any payload change creates a new release +candidate that must receive its own digest, SBOM, and provenance and pass the +applicable blocking qualification suites before the stable tag and publication +are created. + +The stable qualification record contains the final artifact digests, SBOM and +provenance references, and results, and links them to the qualifying nightly +manifest. A nightly result cannot be copied to a different artifact digest. + +The workflow creates the stable Git tag only after all blocking checks pass. +It must not push a tag first and attempt qualification afterward. A failed +weekly run publishes nothing; the next run selects the newest eligible nightly +candidate. + +### Maintenance and backports + +OpenShell maintains two minor release lines: the latest minor and N-1. Support +applies to the newest patch on each line. Users on an older patch update to the +new maintenance patch rather than receiving a separate fix for every historical +patch. + +Maintenance releases contain critical reliability fixes and security fixes. +They do not backport features. A fix is developed on the appropriate primary +branch and backported to a `release/.` branch when the older line +is affected. Each backport passes the compatibility, regression, packaging, +and supported upgrade qualification appropriate to that line. + +For example, if `0.3.1` is current and a vulnerability also affects the 0.2 +line, OpenShell publishes the next available `0.2.x` patch from the maintained +0.2 branch. A security release may occur immediately rather than waiting for +the next Tuesday release. + +The documentation identifies the supported minor lines, their latest patches, +and their end-of-support dates. When a new minor release makes an older line +N-2, the older line remains supported for at least 90 days after the replacing +minor release becomes stable. The project announces the end-of-support date +when the replacing minor is released. This calendar floor supplements the N-1 +rule; it does not shorten a line's support while it remains N-1. + +## Implementation plan + +1. **Keep per-commit dev releases and publish 0.1.0 nightlies.** Build every + commit to `main` with all development features, and publish + `0.1.0-nightly` candidates with the release feature set leading to 0.1.0. +2. **Make the necessary breaking API changes.** Use the pre-0.1.0 window to + finalize stable interfaces, move evolving APIs to experimental packages, + and establish the compatibility baseline. +3. **Build qualification tests and release machinery.** Automate compatibility + detection, conformance, upgrade, breaking API change review, security + qualification, artifact validation, and release publication gates. +4. **Release 0.1.0.** Promote a qualified nightly candidate, publish the stable + artifacts and support guidance, and begin the weekly release cadence. diff --git a/rfc/0014-release-stability/build-matrix.md b/rfc/0014-release-stability/build-matrix.md new file mode 100644 index 0000000000..826a0f6791 --- /dev/null +++ b/rfc/0014-release-stability/build-matrix.md @@ -0,0 +1,70 @@ +# RFC 0014 Supplement - Build Matrix + +This supplement defines the build targets for the release system described by +RFC 0014. The targets follow the structure of the +[proposed support matrix](https://github.com/NVIDIA/OpenShell/blob/d575cf85f8c520774cc3e307ec1bcdabf57cd682/docs/reference/support-matrix.mdx) +and describe the intended final state. + +These tables enumerate build and capability targets. They do not imply that +every cross-product of platform, architecture, installation method, driver, +topology, and capability is supported. The +[release qualification supplement](release-qualification.md) defines the +minimal blocking release gate. It contains one conformance workflow per compute +driver, one Kubernetes conformance workflow per supported gateway topology, and +one upgrade workflow per installation package, plus one breaking API change +review and one security review per candidate. Other supported dimensions are +exercised as subcases or separate CI controls rather than as a Cartesian product +of release jobs. + +## Platforms + +| Platform | Installation methods | Requirements | +| --- | --- | --- | +| macOS (Apple Silicon) | Homebrew | macOS 13.3 or later | +| Linux (x86_64, arm64) | APT/DEB, RPM, Snap | glibc 2.28 or later | +| Windows (x86_64, arm64) | MSI, WinGet | Documented minimum Windows version and MSVC toolchain | + +Package installers include the CLI, TUI, gateway, and supported local drivers. +Standalone CLI and TUI binaries are also published for remote gateway access. + +## Compute drivers + +| Driver | Supported hosts | Minimum version | Requirements | +| --- | --- | --- | --- | +| Docker | macOS, Linux, Windows | 28.0.4 or later | Docker Engine or Docker Desktop | +| Podman | macOS, Linux, Windows | 5.x | Podman socket, rootless networking, and cgroups v2 | +| MicroVM | macOS, Linux | macOS 13.3 or later; KVM on Linux | Host virtualization, Hypervisor.framework on macOS, and KVM on Linux | +| Kubernetes | Kubernetes clusters | 1.29 or later | Helm 3.x and a compatible Agent Sandbox controller and CRDs | + +## GPU support + +| Compute driver | Supported environment | Device interface | Requirements and limits | +| --- | --- | --- | --- | +| Docker | Linux; Windows through WSL2 | NVIDIA CDI | CDI-enabled runtime with visible NVIDIA devices; default and counted GPU requests | +| Podman | Linux; Windows through WSL2 | NVIDIA CDI | Visible NVIDIA CDI devices; default and counted GPU requests | +| MicroVM | Linux | QEMU/VFIO PCI passthrough | IOMMU, VFIO, root privileges, compatible sandbox image, and one GPU per sandbox | +| Kubernetes | Linux GPU nodes | `nvidia.com/gpu` extended resources | NVIDIA GPU Device Plugin and a compatible sandbox image | + +Release qualification accepts current CUDA drivers and validates against the +Tesla Recommended Driver branches. + +## Kubernetes + +| Component | Supported version | Notes | +| --- | --- | --- | +| Kubernetes | 1.29 or later | Required for Helm deployments and sandbox scheduling | +| Helm | 3.x | Required to install and upgrade the OpenShell chart | +| Agent Sandbox controller and CRDs | Compatible release | Required before installing the OpenShell chart | +| User namespaces | 1.33 or later | Optional; enables `hostUsers: false` for UID remapping | + +GKE Standard, GKE Autopilot, and OpenShift 4.x are supported. OpenShift uses +the OpenShift-specific SCC binding and chart configuration. + +## SDKs + +| SDK | Minimum version | +| --- | --- | +| Python | 3.12 | +| TypeScript | 5.7 | +| Rust | 1.90 | +| Go | 1.24 | diff --git a/rfc/0014-release-stability/release-qualification.md b/rfc/0014-release-stability/release-qualification.md new file mode 100644 index 0000000000..b9be6128f0 --- /dev/null +++ b/rfc/0014-release-stability/release-qualification.md @@ -0,0 +1,118 @@ +# RFC 0014 Supplement - Release Qualification + +A nightly candidate is eligible for stable release only after its published +artifacts pass every required [conformance](#conformance) and +[upgrade](#upgrade) workflow, its +[breaking API change review](#breaking-api-change-review), and its +[security review](#security-review). + +## Conformance + +Conformance runs for different OpenShell driver and host configurations. +Kubernetes runs once per supported gateway topology. Each workflow installs the +candidate in one representative environment and verifies the supported +OpenShell behavior for that driver and topology. + +For each driver, the suite: + +1. Installs the candidate artifacts and starts the gateway and selected runtime. +2. Verifies gateway health, version reporting, TLS, authentication, and + authorization. +3. Creates a sandbox, connects to it, executes commands, and exercises stop, + restart, and restore behavior where supported. +4. Exercises filesystem, process, network, credential, and inference policy + enforcement, including expected denial behavior. +5. Verifies the configured compute driver, credential driver, interceptor, and + middleware contracts, including capability discovery, validation, errors, + restart reconciliation, and cleanup. +6. Deletes the sandbox and confirms that runtime, network, credential, and + persisted resources are removed. + +Conformance passes only when every driver workflow completes without an +unexpected skip or retry-dependent result. A workflow may exercise relevant +GPU, authentication, credential-driver, interceptor, middleware, and +client/server skew variants as subcases without creating separate workflows. +Unsupported capabilities must return documented errors rather than fail +silently. + +Each workflow uses one representative environment for the compute driver. It +may run multiple capability subcases inside that environment without creating +additional workflows. Kubernetes uses a separate blocking workflow for each +supported gateway topology. + +| ID | Compute driver | Representative environment | Gateway configuration | +| --- | --- | --- | --- | +| C01 | Docker | Ubuntu x86_64 with Docker 28.0.4 | Local gateway; TLS and sandbox mTLS; credentials; CDI GPU when stable | +| C02 | Podman | Fedora x86_64 with Podman 5.x rootless | Local gateway; TLS and sandbox mTLS; credentials; CDI GPU when stable | +| C03 | MicroVM | Linux x86_64 with KVM and IOMMU | Local gateway; libkrun CPU; TLS and sandbox mTLS; QEMU/VFIO GPU when stable | +| C04 | Kubernetes | Kubernetes 1.29 | Sidecar, three replicas; external PostgreSQL; Kubernetes Secrets; TLS and OIDC; GPU when stable | +| C05 | Kubernetes | Kubernetes 1.29 | Combined, three replicas; external PostgreSQL; Kubernetes Secrets; TLS and OIDC; GPU when stable | + +## Upgrade + +Upgrade runs once per supported product installation package. It verifies that +users can move from every supported source release to the candidate without +reinstalling or losing supported state. + +For each installation package, the suite: + +1. Installs the source release and creates representative gateways, sandboxes, + policies, providers, credentials, and persisted state. +2. Exercises the source installation to establish a known-good baseline. +3. Performs the documented in-place upgrade using the published candidate + artifacts. +4. Verifies schema and state migrations, gateway health, existing resources, + policy behavior, and new sandbox creation. +5. Runs a post-upgrade smoke test that verifies existing resources and creates + and deletes a new sandbox. +6. Exercises rollback when rollback is part of the supported upgrade contract. + +| ID | Installation package | Representative environment | Drivers | Upgrade path | +| --- | --- | --- | --- | --- | +| U01 | Homebrew formula | macOS on Apple Silicon | MicroVM | Previous stable formula to candidate formula | +| U02 | DEB through APT | Ubuntu x86_64 | Docker | Previous stable repository package to candidate package | +| U03 | RPM | Fedora x86_64 | Podman | Previous stable repository package to candidate package | +| U04 | Snap | Ubuntu x86_64 | Docker | Previous stable revision to candidate revision | +| U05 | Windows MSI through WinGet | Windows x86_64 | Docker Desktop | Previous stable MSI to candidate MSI | +| U06 | Helm chart | Kubernetes 1.29 | Kubernetes | Previous stable chart and images to candidate chart and image digests | + +## Breaking API change review + +Breaking API change review runs once per candidate. It compares the candidate's +stable protobuf and public SDK interfaces with the latest stable baseline and +any additional baseline required by the N-1 maintenance promise. The review: + +1. Runs protobuf compatibility checks against the supported descriptor + baselines. +2. Runs language-specific compatibility checks for generated and hand-written + SDK interfaces. +3. Classifies each detected change as stable, experimental, or development-only + and records the evidence in the qualification record. +4. Confirms that a patch release contains no breaking stable API change. +5. For an intentional breaking change in a minor release, confirms the required + project version, protobuf package revision where applicable, migration + guidance, release notes, and approval. + +Breaking API change review passes when no unaddressed breaking change affects a +stable API baseline and every intentional minor-release break satisfies the +versioning and migration requirements. + +## Security review + +Security review runs once per candidate and covers the complete candidate +artifact set. A designated security approver: + +1. Reviews vulnerability, dependency, container, and infrastructure scan + results for the candidate artifacts. +2. Reviews changes since the previous stable release to authentication, + authorization, policy enforcement, sandbox isolation, credentials, and the + update trust boundary. +3. Confirms that required penetration testing is current for the affected trust + boundaries. +4. Records the scope, evidence, findings, and disposition in the qualification + record. + +Security review passes when no unresolved critical or high-severity finding +affects a supported configuration. A medium-severity finding requires an +explicit documented disposition before release. Low and informational findings +remain tracked but do not block by default. From 45d6875ac105e23466ca2f2cc4d3b0411902c06d Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 10 Aug 2026 23:18:42 -0700 Subject: [PATCH 02/18] docs(rfc): link review pull request Signed-off-by: Drew Newberry --- rfc/0014-release-stability/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/rfc/0014-release-stability/README.md b/rfc/0014-release-stability/README.md index 4a2f9b41f7..3ff4db495d 100644 --- a/rfc/0014-release-stability/README.md +++ b/rfc/0014-release-stability/README.md @@ -4,6 +4,7 @@ authors: state: review links: - https://github.com/NVIDIA/OpenShell/pull/2148 + - https://github.com/NVIDIA/OpenShell/pull/2695 --- # RFC 0014 - Alpha Exit Criteria and Stable Release Policy From b3b9e2d1651cd3e7f92dcf8c684458503161f9fe Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Tue, 11 Aug 2026 08:54:51 -0700 Subject: [PATCH 03/18] docs(rfc): summarize release proposal Signed-off-by: Drew Newberry --- rfc/0014-release-stability/README.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/rfc/0014-release-stability/README.md b/rfc/0014-release-stability/README.md index 3ff4db495d..3dbb03f052 100644 --- a/rfc/0014-release-stability/README.md +++ b/rfc/0014-release-stability/README.md @@ -17,6 +17,15 @@ It defines release qualification requirements, compatibility guidelines for stable and evolving APIs, per-commit development releases, nightly builds, and weekly stable releases. +- Publish per-commit development releases, nightly candidates, and qualified + stable releases every Tuesday. +- Establish stable and experimental API maturity, compatibility and versioning + rules, and maintenance for the latest and N-1 minor release lines. +- Block stable publication on conformance, upgrade, breaking API change, and + security qualification across the supported release matrix. +- Promote qualified binary payloads unchanged across standalone downloads, + packages, and container images, with recorded digests, SBOMs, and provenance. + ## Motivation OpenShell's alpha process supports rapid iteration but does not define which From ab0e5bb0f76aa4eb7253c3d70cc7cb0ea3b143e5 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Tue, 11 Aug 2026 17:00:57 -0700 Subject: [PATCH 04/18] docs(rfc): replace nightlies with release candidates Signed-off-by: Drew Newberry --- rfc/0014-release-stability/README.md | 95 ++++++++++--------- .../release-qualification.md | 2 +- 2 files changed, 49 insertions(+), 48 deletions(-) diff --git a/rfc/0014-release-stability/README.md b/rfc/0014-release-stability/README.md index 3dbb03f052..11628e4595 100644 --- a/rfc/0014-release-stability/README.md +++ b/rfc/0014-release-stability/README.md @@ -14,11 +14,11 @@ links: The goal of this RFC is to define OpenShell's exit from alpha and establish a predictable release cycle for production users and ecosystem developers. It defines release qualification requirements, compatibility guidelines for -stable and evolving APIs, per-commit development releases, nightly builds, and -weekly stable releases. +stable and evolving APIs, per-commit development releases, nightly-generated +release candidates, and weekly stable releases. -- Publish per-commit development releases, nightly candidates, and qualified - stable releases every Tuesday. +- Publish development releases for every commit to `main`, build release + candidates nightly, and publish qualified stable releases every Tuesday. - Establish stable and experimental API maturity, compatibility and versioning rules, and maintenance for the latest and N-1 minor release lines. - Block stable publication on conformance, upgrade, breaking API change, and @@ -61,18 +61,17 @@ development compilation flags and features. They are not qualification evidence, are not supported deployment pins, and are not candidates for stable promotion. -OpenShell also publishes nightly prereleases of the next expected patch -release. After `0.1.1`, a nightly release may be identified as -`0.1.2-nightly.20260811.1`, where the final component distinguishes multiple -candidates created on the same date. Git tags add the normal `v` prefix. Each -nightly identifies one source commit and one artifact manifest. A floating -`nightly` alias may point to the newest candidate for convenience, but the alias -is not qualification evidence and is not a supported deployment pin. +OpenShell builds a release candidate nightly for the next expected stable +release when `main` has changed and normal CI passes. After `0.1.1`, candidates +are numbered `0.1.2-rc.1`, `0.1.2-rc.2`, and so on. Git tags add the normal `v` +prefix. Each release candidate identifies one source commit and one artifact +manifest, uses the release feature set, and is the unit of release +qualification. Release candidates are not supported production releases. -Release tooling maps development and nightly versions into the syntax and -ordering rules required by Python, Cargo, Debian, RPM, Snap, OCI, Helm, and +Release tooling maps development and release candidate versions into the syntax +and ordering rules required by Python, Cargo, Debian, RPM, Snap, OCI, Helm, and other publication targets. The mapping must preserve the invariant that these -releases sort before their corresponding stable release wherever the package +prereleases sort before their corresponding stable release wherever the package ecosystem supports prerelease ordering. ### Project version and compatibility contract @@ -118,12 +117,13 @@ Capability maturity is independent from the release that contains it: | Stable | Stable protobuf packages such as `v1` or `v2` | Covered by the release compatibility contract | | Experimental | Explicit unstable package such as `v1beta1` | May change with documented migration guidance | -Stable and experimental capabilities may be included in stable, nightly, or -development artifacts according to the release configuration. Availability -only in a development or nightly build is not a third maturity level and does -not make the capability experimental. The capability must still be classified -independently as stable or experimental. A capability absent from stable -artifacts has no stable release availability or support promise. +Stable and experimental capabilities may be included in stable, release +candidate, or development artifacts according to the release configuration. +Availability only in a development or release candidate build is not a third +maturity level and does not make the capability experimental. The capability +must still be classified independently as stable or experimental. A capability +absent from stable artifacts has no stable release availability or support +promise. A new API that is useful to release but whose design is still evolving starts with a package such as `v1beta1`. It may evolve to `v1beta2` in a patch release @@ -134,16 +134,16 @@ stable `v1` package; it does not rename the experimental package in place. Features that are not ready to be released are protected by named compile-time features such as `unstable-` and collected under a `dev` feature. Development releases are built with all development compilation flags and -features enabled. Stable tagged releases and nightlies build service binaries, -CLI commands, configuration fields, and documentation without those features. -For now, SDK packages may include the generated types and client methods for -development capabilities in every release so the project does not need to -publish separate development and release SDK variants. Their presence in an SDK -does not make the capability available or supported: the target service must -advertise and implement it, and only stable SDK interfaces are covered by the -compatibility contract. CI for every commit to `main` builds and tests both the -development feature set and the release feature set so compile-gated -development cannot silently break supported builds. +features enabled. Stable tagged releases and release candidates build service +binaries, CLI commands, configuration fields, and documentation without those +features. For now, SDK packages may include the generated types and client +methods for development capabilities in every release so the project does not +need to publish separate development and release SDK variants. Their presence +in an SDK does not make the capability available or supported: the target +service must advertise and implement it, and only stable SDK interfaces are +covered by the compatibility contract. CI for every commit to `main` builds and +tests both the development feature set and the release feature set so +compile-gated development cannot silently break supported builds. ### Breaking changes and API versioning @@ -163,16 +163,16 @@ a minor project release even when no protobuf package changes. Conversely, a new experimental `v1beta2` package does not require a minor project release when it does not break any stable interface. -Breaking-change detection runs during code review and again during nightly -qualification. Stable protobuf packages use Buf's `FILE` rules against the -latest stable baseline and any additional supported baseline needed for the -N-1 maintenance promise. Language-specific API checks or agent review skills -cover the public SDKs. +Breaking-change detection runs during code review and again during release +candidate qualification. Stable protobuf packages use Buf's `FILE` rules +against the latest stable baseline and any additional supported baseline needed +for the N-1 maintenance promise. Language-specific API checks or agent review +skills cover the public SDKs. Contract fixtures cover CLI, configuration, policy, and Helm surfaces. Upgrade and version-skew tests cover semantic and persisted-state behavior that a schema diff cannot detect. -### Nightly qualification and stable release promotion +### Release candidate qualification and stable release promotion The release system separates candidate creation, qualification, and stable publication: @@ -181,8 +181,8 @@ publication: flowchart LR A["Commit to main"] --> B["Dev release
dev features enabled"] A --> C["Qualified main commit"] - C --> D["Nightly candidate
release feature set"] - D --> E["Nightly qualification"] + C --> D["Nightly RC build
release feature set"] + D --> E["RC qualification"] E -->|"pass"| F["Eligible Tuesday candidate"] E -->|"fail"| G["No stable release"] F --> H["Build or promote stable artifacts"] @@ -191,7 +191,7 @@ flowchart LR I -->|"fail"| G ``` -Every nightly candidate produces a manifest containing its canonical version, +Every release candidate produces a manifest containing its canonical version, full source commit, build inputs, artifact names and digests, SBOM and provenance references, and qualification results. Qualification installs and exercises the candidate artifacts wherever practical rather than substituting a source build. @@ -214,7 +214,7 @@ The initial release targets are defined in the [build matrix](build-matrix.md), and blocking coverage is defined in the [release qualification supplement](release-qualification.md). -The weekly release selects the newest eligible nightly candidate published +The weekly release selects the newest eligible release candidate published before a documented cutoff. No source change is allowed between candidate qualification and stable publication. The candidate build produces canonical binary payloads once; standalone downloads, OCI images, and installation @@ -228,12 +228,13 @@ applicable blocking qualification suites before the stable tag and publication are created. The stable qualification record contains the final artifact digests, SBOM and -provenance references, and results, and links them to the qualifying nightly -manifest. A nightly result cannot be copied to a different artifact digest. +provenance references, and results, and links them to the qualifying release +candidate manifest. A release candidate result cannot be copied to a different +artifact digest. The workflow creates the stable Git tag only after all blocking checks pass. It must not push a tag first and attempt qualification afterward. A failed -weekly run publishes nothing; the next run selects the newest eligible nightly +weekly run publishes nothing; the next run selects the newest eligible release candidate. ### Maintenance and backports @@ -263,14 +264,14 @@ rule; it does not shorten a line's support while it remains N-1. ## Implementation plan -1. **Keep per-commit dev releases and publish 0.1.0 nightlies.** Build every - commit to `main` with all development features, and publish - `0.1.0-nightly` candidates with the release feature set leading to 0.1.0. +1. **Keep per-commit dev releases and build 0.1.0 RCs nightly.** Build every + commit to `main` with all development features, and publish sequential + `0.1.0-rc.N` candidates with the release feature set leading to 0.1.0. 2. **Make the necessary breaking API changes.** Use the pre-0.1.0 window to finalize stable interfaces, move evolving APIs to experimental packages, and establish the compatibility baseline. 3. **Build qualification tests and release machinery.** Automate compatibility detection, conformance, upgrade, breaking API change review, security qualification, artifact validation, and release publication gates. -4. **Release 0.1.0.** Promote a qualified nightly candidate, publish the stable +4. **Release 0.1.0.** Promote a qualified release candidate, publish the stable artifacts and support guidance, and begin the weekly release cadence. diff --git a/rfc/0014-release-stability/release-qualification.md b/rfc/0014-release-stability/release-qualification.md index b9be6128f0..cf86cfe769 100644 --- a/rfc/0014-release-stability/release-qualification.md +++ b/rfc/0014-release-stability/release-qualification.md @@ -1,6 +1,6 @@ # RFC 0014 Supplement - Release Qualification -A nightly candidate is eligible for stable release only after its published +A release candidate is eligible for stable release only after its published artifacts pass every required [conformance](#conformance) and [upgrade](#upgrade) workflow, its [breaking API change review](#breaking-api-change-review), and its From 83774676e38635b2956a096efda2d3267c692d3d Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Tue, 11 Aug 2026 17:09:12 -0700 Subject: [PATCH 05/18] docs(rfc): add breaking change examples Signed-off-by: Drew Newberry --- rfc/0014-release-stability/README.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/rfc/0014-release-stability/README.md b/rfc/0014-release-stability/README.md index 11628e4595..3a64ffc44f 100644 --- a/rfc/0014-release-stability/README.md +++ b/rfc/0014-release-stability/README.md @@ -172,6 +172,15 @@ Contract fixtures cover CLI, configuration, policy, and Helm surfaces. Upgrade and version-skew tests cover semantic and persisted-state behavior that a schema diff cannot detect. +The following examples illustrate how these rules affect a release candidate: + +| Example | Concrete change | Release treatment | +| --- | --- | --- | +| Breaking stable Protobuf contract | `SandboxSpec.policy = 7` to `SandboxSpec.policy = 10` | Blocks a patch RC and requires a versioned API change. | +| Breaking experimental Python SDK method | `create_sandbox(timeout=30)` to `create_sandbox(deadline=...)` | May ship in a patch release with migration notes. | +| Breaking stable policy document | `endpoints:` to `destinations:` | Blocks a patch RC unless both fields remain supported. | +| Breaking stable CLI contract | `--policy policy.yaml` to `--policy-file policy.yaml` | Requires retaining the old flag as an alias or shipping a minor release. | + ### Release candidate qualification and stable release promotion The release system separates candidate creation, qualification, and stable From d3b9c0e003a054395b91b1315350c85990f50073 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Tue, 11 Aug 2026 17:10:30 -0700 Subject: [PATCH 06/18] docs(rfc): simplify compatibility proposal Signed-off-by: Drew Newberry --- rfc/0014-release-stability/README.md | 38 +++------------------------- 1 file changed, 3 insertions(+), 35 deletions(-) diff --git a/rfc/0014-release-stability/README.md b/rfc/0014-release-stability/README.md index 3a64ffc44f..1c6fe8897c 100644 --- a/rfc/0014-release-stability/README.md +++ b/rfc/0014-release-stability/README.md @@ -1,6 +1,6 @@ --- authors: - - "@anewberry" + - "@drew" state: review links: - https://github.com/NVIDIA/OpenShell/pull/2148 @@ -21,10 +21,8 @@ release candidates, and weekly stable releases. candidates nightly, and publish qualified stable releases every Tuesday. - Establish stable and experimental API maturity, compatibility and versioning rules, and maintenance for the latest and N-1 minor release lines. -- Block stable publication on conformance, upgrade, breaking API change, and - security qualification across the supported release matrix. -- Promote qualified binary payloads unchanged across standalone downloads, - packages, and container images, with recorded digests, SBOMs, and provenance. +- Maintain a release qualification pipeline covering conformance, upgrades, + API changes, and security reviews across the supported release matrix. ## Motivation @@ -68,12 +66,6 @@ prefix. Each release candidate identifies one source commit and one artifact manifest, uses the release feature set, and is the unit of release qualification. Release candidates are not supported production releases. -Release tooling maps development and release candidate versions into the syntax -and ordering rules required by Python, Cargo, Debian, RPM, Snap, OCI, Helm, and -other publication targets. The mapping must preserve the invariant that these -prereleases sort before their corresponding stable release wherever the package -ecosystem supports prerelease ordering. - ### Project version and compatibility contract Version 0.1.0 begins OpenShell's supported compatibility contract. For @@ -83,30 +75,6 @@ the 0.x series: functionality. They do not intentionally break a stable interface. - An unavoidable breaking change to any stable interface starts a new minor release and resets the patch version, for example `0.1.x` to `0.2.0`. -- Security fixes may make the narrowest necessary incompatible change when no - safe compatible remediation exists. The release notes and security guidance - must describe the operator action without exposing embargoed information. -- Deprecation is preferred to removal. Except for urgent security or safety - reasons, a deprecated stable interface remains available for the rest of its - minor release line and is removed only in a later minor release. - -The project version covers more than protobuf wire compatibility. Before -0.1.0, OpenShell publishes an inventory that classifies at least these surfaces: - -| Surface | Stable promise when designated stable | -| --- | --- | -| Protobuf and generated SDK APIs | Source, wire, JSON, and documented semantic compatibility | -| Hand-written SDK APIs | Documented public types, methods, and behavior remain compatible | -| CLI | Documented commands, flags, exit behavior, and machine-readable output remain compatible | -| Gateway configuration | Existing supported configuration continues to parse with equivalent semantics | -| Sandbox policy schema | Existing supported policies continue to validate and enforce equivalent intent | -| Helm and installation configuration | Supported values, environment variables, and upgrade paths remain compatible | -| Extension contracts | Stable driver, interceptor, and middleware contracts evolve additively | -| Persisted operational state | Supported upgrades migrate state without requiring a clean installation | - -The 0.1.0 schemas, SDK signatures, CLI contract fixtures, configuration and -policy schemas, and upgrade fixtures become the initial compatibility baseline. -Every later stable release records which baseline it was checked against. ### Capability maturity and release availability From f49a7d9e58905e7ba60e36a75c24d679f21c435f Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Tue, 11 Aug 2026 17:46:31 -0700 Subject: [PATCH 07/18] docs(rfc): add SELinux Podman coverage Signed-off-by: Drew Newberry --- rfc/0014-release-stability/release-qualification.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/rfc/0014-release-stability/release-qualification.md b/rfc/0014-release-stability/release-qualification.md index cf86cfe769..a490ad9422 100644 --- a/rfc/0014-release-stability/release-qualification.md +++ b/rfc/0014-release-stability/release-qualification.md @@ -40,14 +40,18 @@ may run multiple capability subcases inside that environment without creating additional workflows. Kubernetes uses a separate blocking workflow for each supported gateway topology. +### Configurations to test + | ID | Compute driver | Representative environment | Gateway configuration | | --- | --- | --- | --- | | C01 | Docker | Ubuntu x86_64 with Docker 28.0.4 | Local gateway; TLS and sandbox mTLS; credentials; CDI GPU when stable | -| C02 | Podman | Fedora x86_64 with Podman 5.x rootless | Local gateway; TLS and sandbox mTLS; credentials; CDI GPU when stable | +| C02 | Podman | Fedora x86_64 with Podman 5.x rootless and SELinux enforcing | Local gateway; TLS and sandbox mTLS; credentials; CDI GPU when stable | | C03 | MicroVM | Linux x86_64 with KVM and IOMMU | Local gateway; libkrun CPU; TLS and sandbox mTLS; QEMU/VFIO GPU when stable | | C04 | Kubernetes | Kubernetes 1.29 | Sidecar, three replicas; external PostgreSQL; Kubernetes Secrets; TLS and OIDC; GPU when stable | | C05 | Kubernetes | Kubernetes 1.29 | Combined, three replicas; external PostgreSQL; Kubernetes Secrets; TLS and OIDC; GPU when stable | +C02 must pass without disabling SELinux or weakening the host SELinux policy. + ## Upgrade Upgrade runs once per supported product installation package. It verifies that @@ -67,6 +71,8 @@ For each installation package, the suite: and deletes a new sandbox. 6. Exercises rollback when rollback is part of the supported upgrade contract. +### Configurations to test + | ID | Installation package | Representative environment | Drivers | Upgrade path | | --- | --- | --- | --- | --- | | U01 | Homebrew formula | macOS on Apple Silicon | MicroVM | Previous stable formula to candidate formula | From 7e805160d60e8b25424beb25a5b9fe407cef63ac Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Tue, 11 Aug 2026 18:53:10 -0700 Subject: [PATCH 08/18] docs(rfc): simplify capability release rules Signed-off-by: Drew Newberry --- rfc/0014-release-stability/README.md | 43 +++++++++++----------------- 1 file changed, 16 insertions(+), 27 deletions(-) diff --git a/rfc/0014-release-stability/README.md b/rfc/0014-release-stability/README.md index 1c6fe8897c..02820a815f 100644 --- a/rfc/0014-release-stability/README.md +++ b/rfc/0014-release-stability/README.md @@ -85,33 +85,22 @@ Capability maturity is independent from the release that contains it: | Stable | Stable protobuf packages such as `v1` or `v2` | Covered by the release compatibility contract | | Experimental | Explicit unstable package such as `v1beta1` | May change with documented migration guidance | -Stable and experimental capabilities may be included in stable, release -candidate, or development artifacts according to the release configuration. -Availability only in a development or release candidate build is not a third -maturity level and does not make the capability experimental. The capability -must still be classified independently as stable or experimental. A capability -absent from stable artifacts has no stable release availability or support -promise. - -A new API that is useful to release but whose design is still evolving starts -with a package such as `v1beta1`. It may evolve to `v1beta2` in a patch release -because the package name advertises the lack of stable compatibility. Release -notes still explain the change and any migration path. Graduation creates a -stable `v1` package; it does not rename the experimental package in place. - -Features that are not ready to be released are protected by named compile-time -features such as `unstable-` and collected under a `dev` feature. -Development releases are built with all development compilation flags and -features enabled. Stable tagged releases and release candidates build service -binaries, CLI commands, configuration fields, and documentation without those -features. For now, SDK packages may include the generated types and client -methods for development capabilities in every release so the project does not -need to publish separate development and release SDK variants. Their presence -in an SDK does not make the capability available or supported: the target -service must advertise and implement it, and only stable SDK interfaces are -covered by the compatibility contract. CI for every commit to `main` builds and -tests both the development feature set and the release feature set so -compile-gated development cannot silently break supported builds. +Capability maturity and artifact availability are separate. Every capability is +stable or experimental, regardless of whether it appears in stable, release +candidate, or development artifacts. A capability omitted from stable artifacts +has no stable availability or support promise. + +An evolving API may ship in a beta package such as `v1beta1`. It may change to +`v1beta2` in a patch release with release notes and migration guidance. +Graduation adds a stable `v1` package instead of renaming the beta package. + +Unreleased features use named compile-time flags such as `unstable-`, +collected under a `dev` feature. Development releases enable them; stable +releases and release candidates exclude them from service binaries, the CLI, +configuration, and documentation. For now, every SDK package may include their +generated types and client methods, but the target service must implement them +and only stable SDK interfaces have a compatibility guarantee. CI builds and +tests both feature sets on every commit to `main`. ### Breaking changes and API versioning From 2bd79936540275394ab805d371a1775e59dbd7e1 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Tue, 11 Aug 2026 19:01:18 -0700 Subject: [PATCH 09/18] docs(rfc): streamline release stability proposal Signed-off-by: Drew Newberry --- rfc/0014-release-stability/README.md | 68 +++++----------------------- 1 file changed, 12 insertions(+), 56 deletions(-) diff --git a/rfc/0014-release-stability/README.md b/rfc/0014-release-stability/README.md index 02820a815f..115281186d 100644 --- a/rfc/0014-release-stability/README.md +++ b/rfc/0014-release-stability/README.md @@ -17,36 +17,25 @@ It defines release qualification requirements, compatibility guidelines for stable and evolving APIs, per-commit development releases, nightly-generated release candidates, and weekly stable releases. -- Publish development releases for every commit to `main`, build release - candidates nightly, and publish qualified stable releases every Tuesday. -- Establish stable and experimental API maturity, compatibility and versioning +This RFC proposes + +- Development releases for every commit to `main`, nightly release candidates, and qualified stable releases every Tuesday. +- Stable and experimental API maturity, compatibility and versioning rules, and maintenance for the latest and N-1 minor release lines. -- Maintain a release qualification pipeline covering conformance, upgrades, +- A release qualification pipeline covering conformance, upgrades, API changes, and security reviews across the supported release matrix. ## Motivation -OpenShell's alpha process supports rapid iteration but does not define which -artifacts qualify for release, which interfaces users can rely on, or how long +OpenShell's alpha process supports rapid iteration but does not define which interfaces users can rely on, or how long release lines are maintained. OpenShell 0.1.0 is considered suitable for -production use within the published support matrix. This suitability means -that supported platform, architecture, installation method, compute driver, -deployment topology, and capability combinations have passed the required -conformance and upgrade qualification; stable interfaces have an established -compatibility baseline; supported upgrade and rollback paths have been tested; -release artifacts have verified provenance, SBOMs, and digests; and required -security review has found no unresolved blocking issues. Experimental and -unsupported combinations remain clearly identified and are not covered by the -production support promise. +production use within the published support matrix. This means that releases have passed conformance, upgrade, compatibility, artifact, and security checks. ## Proposal ### Release cadence -Starting with 0.1.0, OpenShell documents each release by its version, support -status, and the maturity of individual capabilities. - -OpenShell publishes stable tagged releases intended for production use within +Starting with `0.1.0`, OpenShell publishes stable tagged releases intended for production use within the published support matrix. Stable releases occur every Tuesday and increment the patch version, for example `0.1.1` followed by `0.1.2`. A stable tag is published only when there are changes and every blocking qualification suite @@ -109,13 +98,11 @@ problems and are applied together when appropriate. If a breaking change affects a stable OpenShell surface, the release moves to the next minor version. If the same change is incompatible with a stable -protobuf contract, the protocol also moves to a new major-versioned package, +protobuf contract, the protocol _may_ move to a new major-versioned package, for example `openshell.v1` to `openshell.v2`. The supported server retains the -old protocol for the maintenance window or supplies an explicit migration path; -the package revision does not by itself satisfy the project-level versioning -requirement. +old protocol for a defined maintenance window or supplies an explicit migration path. -A breaking CLI, SDK, configuration, policy, Helm, or state change still requires +A breaking CLI, SDK, configuration, policy, Helm, or state change requires a minor project release even when no protobuf package changes. Conversely, a new experimental `v1beta2` package does not require a minor project release when it does not break any stable interface. @@ -125,9 +112,6 @@ candidate qualification. Stable protobuf packages use Buf's `FILE` rules against the latest stable baseline and any additional supported baseline needed for the N-1 maintenance promise. Language-specific API checks or agent review skills cover the public SDKs. -Contract fixtures cover CLI, configuration, policy, and Helm surfaces. Upgrade -and version-skew tests cover semantic and persisted-state behavior that a schema -diff cannot detect. The following examples illustrate how these rules affect a release candidate: @@ -180,28 +164,7 @@ The initial release targets are defined in the [build matrix](build-matrix.md), and blocking coverage is defined in the [release qualification supplement](release-qualification.md). -The weekly release selects the newest eligible release candidate published -before a documented cutoff. No source change is allowed between candidate -qualification and stable publication. The candidate build produces canonical -binary payloads once; standalone downloads, OCI images, and installation -packages use those same payloads. Content-addressable artifacts such as OCI -images are promoted by digest rather than rebuilt. Package formats whose -metadata embeds the release version may rebuild only the package envelope. They -must not recompile executables or libraries, and the packaged payload digests -must match the candidate manifest. Any payload change creates a new release -candidate that must receive its own digest, SBOM, and provenance and pass the -applicable blocking qualification suites before the stable tag and publication -are created. - -The stable qualification record contains the final artifact digests, SBOM and -provenance references, and results, and links them to the qualifying release -candidate manifest. A release candidate result cannot be copied to a different -artifact digest. - -The workflow creates the stable Git tag only after all blocking checks pass. -It must not push a tag first and attempt qualification afterward. A failed -weekly run publishes nothing; the next run selects the newest eligible release -candidate. +The weekly release selects the newest eligible release candidate and promotes it to the next stable release. ### Maintenance and backports @@ -221,13 +184,6 @@ line, OpenShell publishes the next available `0.2.x` patch from the maintained 0.2 branch. A security release may occur immediately rather than waiting for the next Tuesday release. -The documentation identifies the supported minor lines, their latest patches, -and their end-of-support dates. When a new minor release makes an older line -N-2, the older line remains supported for at least 90 days after the replacing -minor release becomes stable. The project announces the end-of-support date -when the replacing minor is released. This calendar floor supplements the N-1 -rule; it does not shorten a line's support while it remains N-1. - ## Implementation plan 1. **Keep per-commit dev releases and build 0.1.0 RCs nightly.** Build every From 0b7a903113f199ab4532c130332bfebfcb496013 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Tue, 11 Aug 2026 19:05:34 -0700 Subject: [PATCH 10/18] docs(rfc): simplify release qualification criteria Signed-off-by: Drew Newberry --- .../release-qualification.md | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/rfc/0014-release-stability/release-qualification.md b/rfc/0014-release-stability/release-qualification.md index a490ad9422..dea912f8bd 100644 --- a/rfc/0014-release-stability/release-qualification.md +++ b/rfc/0014-release-stability/release-qualification.md @@ -35,10 +35,9 @@ client/server skew variants as subcases without creating separate workflows. Unsupported capabilities must return documented errors rather than fail silently. -Each workflow uses one representative environment for the compute driver. It +Each workflow uses one representative environment for the configuration under test. It may run multiple capability subcases inside that environment without creating -additional workflows. Kubernetes uses a separate blocking workflow for each -supported gateway topology. +additional workflows. ### Configurations to test @@ -50,8 +49,6 @@ supported gateway topology. | C04 | Kubernetes | Kubernetes 1.29 | Sidecar, three replicas; external PostgreSQL; Kubernetes Secrets; TLS and OIDC; GPU when stable | | C05 | Kubernetes | Kubernetes 1.29 | Combined, three replicas; external PostgreSQL; Kubernetes Secrets; TLS and OIDC; GPU when stable | -C02 must pass without disabling SELinux or weakening the host SELinux policy. - ## Upgrade Upgrade runs once per supported product installation package. It verifies that @@ -111,14 +108,11 @@ artifact set. A designated security approver: 1. Reviews vulnerability, dependency, container, and infrastructure scan results for the candidate artifacts. 2. Reviews changes since the previous stable release to authentication, - authorization, policy enforcement, sandbox isolation, credentials, and the - update trust boundary. + authorization, policy enforcement, sandbox isolation, credentials, and any updated trust boundary. 3. Confirms that required penetration testing is current for the affected trust boundaries. 4. Records the scope, evidence, findings, and disposition in the qualification record. Security review passes when no unresolved critical or high-severity finding -affects a supported configuration. A medium-severity finding requires an -explicit documented disposition before release. Low and informational findings -remain tracked but do not block by default. +affects a supported configuration. From 9f92370cdeb7eb9ed0a8ca71eb71be937df730af Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Tue, 11 Aug 2026 19:11:40 -0700 Subject: [PATCH 11/18] docs(rfc): clarify alpha exit motivation Signed-off-by: Drew Newberry --- rfc/0014-release-stability/README.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/rfc/0014-release-stability/README.md b/rfc/0014-release-stability/README.md index 115281186d..9bf89b7ab1 100644 --- a/rfc/0014-release-stability/README.md +++ b/rfc/0014-release-stability/README.md @@ -13,11 +13,8 @@ links: The goal of this RFC is to define OpenShell's exit from alpha and establish a predictable release cycle for production users and ecosystem developers. -It defines release qualification requirements, compatibility guidelines for -stable and evolving APIs, per-commit development releases, nightly-generated -release candidates, and weekly stable releases. -This RFC proposes +We propose - Development releases for every commit to `main`, nightly release candidates, and qualified stable releases every Tuesday. - Stable and experimental API maturity, compatibility and versioning @@ -27,9 +24,15 @@ This RFC proposes ## Motivation -OpenShell's alpha process supports rapid iteration but does not define which interfaces users can rely on, or how long -release lines are maintained. OpenShell 0.1.0 is considered suitable for -production use within the published support matrix. This means that releases have passed conformance, upgrade, compatibility, artifact, and security checks. +The goal is to exit alpha without slowing OpenShell's development. Releases +should remain frequent and automated, and experimental APIs should be able to +evolve quickly enough to keep pace with the ecosystem. At the same time, users +need stable interfaces they can confidently build on. + +Starting with `0.1.0`, OpenShell provides both: a defined compatibility contract +for stable interfaces and room to evolve experimental capabilities. Releases +are suitable for production use within the published support matrix only after +passing conformance, upgrade, compatibility, artifact, and security checks. ## Proposal From 71d8edd3b2f4e814ba5d8f92511de3b2257812d8 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Tue, 11 Aug 2026 19:39:21 -0700 Subject: [PATCH 12/18] docs(rfc): refine release qualification policy Signed-off-by: Drew Newberry --- rfc/0014-release-stability/README.md | 42 +++++++--------- .../release-qualification.md | 48 ++++++++----------- 2 files changed, 37 insertions(+), 53 deletions(-) diff --git a/rfc/0014-release-stability/README.md b/rfc/0014-release-stability/README.md index 9bf89b7ab1..7b71335a2f 100644 --- a/rfc/0014-release-stability/README.md +++ b/rfc/0014-release-stability/README.md @@ -30,9 +30,10 @@ evolve quickly enough to keep pace with the ecosystem. At the same time, users need stable interfaces they can confidently build on. Starting with `0.1.0`, OpenShell provides both: a defined compatibility contract -for stable interfaces and room to evolve experimental capabilities. Releases -are suitable for production use within the published support matrix only after -passing conformance, upgrade, compatibility, artifact, and security checks. +for stable interfaces and room to evolve experimental APIs and features. +Releases are suitable for production use within the published support matrix +only after passing conformance, upgrade, compatibility, artifact, and security +checks. ## Proposal @@ -53,52 +54,43 @@ promotion. OpenShell builds a release candidate nightly for the next expected stable release when `main` has changed and normal CI passes. After `0.1.1`, candidates -are numbered `0.1.2-rc.1`, `0.1.2-rc.2`, and so on. Git tags add the normal `v` -prefix. Each release candidate identifies one source commit and one artifact -manifest, uses the release feature set, and is the unit of release -qualification. Release candidates are not supported production releases. +are numbered `0.1.2-rc.1`, `0.1.2-rc.2`, and so on. A release candidate is promoted to a stable release tag as part of the weekly release pipeline once the candidate has passed qualification. ### Project version and compatibility contract -Version 0.1.0 begins OpenShell's supported compatibility contract. For -the 0.x series: +Version `0.1.0` begins OpenShell's supported compatibility contract. For +the `0.x` series: - Patch releases may contain bug fixes and additive, backward-compatible functionality. They do not intentionally break a stable interface. - An unavoidable breaking change to any stable interface starts a new minor release and resets the patch version, for example `0.1.x` to `0.2.0`. -### Capability maturity and release availability +### API and feature maturity -Capability maturity is independent from the release that contains it: +The maturity of an API or feature is independent of the release that contains +it: | Maturity | API naming | Compatibility | | --- | --- | --- | | Stable | Stable protobuf packages such as `v1` or `v2` | Covered by the release compatibility contract | | Experimental | Explicit unstable package such as `v1beta1` | May change with documented migration guidance | -Capability maturity and artifact availability are separate. Every capability is -stable or experimental, regardless of whether it appears in stable, release -candidate, or development artifacts. A capability omitted from stable artifacts -has no stable availability or support promise. +Every API and feature is stable or experimental, regardless of whether it +appears in stable, release candidate, or development artifacts. An evolving API may ship in a beta package such as `v1beta1`. It may change to `v1beta2` in a patch release with release notes and migration guidance. Graduation adds a stable `v1` package instead of renaming the beta package. Unreleased features use named compile-time flags such as `unstable-`, -collected under a `dev` feature. Development releases enable them; stable +collected under a `dev` compilation flag. Development releases enable them; stable releases and release candidates exclude them from service binaries, the CLI, configuration, and documentation. For now, every SDK package may include their -generated types and client methods, but the target service must implement them -and only stable SDK interfaces have a compatibility guarantee. CI builds and -tests both feature sets on every commit to `main`. +generated types and client methods. ### Breaking changes and API versioning -A project release version bump and a protocol package revision solve different -problems and are applied together when appropriate. - If a breaking change affects a stable OpenShell surface, the release moves to the next minor version. If the same change is incompatible with a stable protobuf contract, the protocol _may_ move to a new major-versioned package, @@ -120,7 +112,7 @@ The following examples illustrate how these rules affect a release candidate: | Example | Concrete change | Release treatment | | --- | --- | --- | -| Breaking stable Protobuf contract | `SandboxSpec.policy = 7` to `SandboxSpec.policy = 10` | Blocks a patch RC and requires a versioned API change. | +| Breaking stable Protobuf contract | `v1: string policy = 7` to `v2: PolicyReference policy = 7` | Blocks a patch RC; ships as `v2` in a minor release while `v1` remains supported. | | Breaking experimental Python SDK method | `create_sandbox(timeout=30)` to `create_sandbox(deadline=...)` | May ship in a patch release with migration notes. | | Breaking stable policy document | `endpoints:` to `destinations:` | Blocks a patch RC unless both fields remain supported. | | Breaking stable CLI contract | `--policy policy.yaml` to `--policy-file policy.yaml` | Requires retaining the old flag as an alias or shipping a minor release. | @@ -144,7 +136,7 @@ flowchart LR I -->|"fail"| G ``` -Every release candidate produces a manifest containing its canonical version, +Every release candidate produces a manifest containing its version, full source commit, build inputs, artifact names and digests, SBOM and provenance references, and qualification results. Qualification installs and exercises the candidate artifacts wherever practical rather than substituting a source build. @@ -171,7 +163,7 @@ The weekly release selects the newest eligible release candidate and promotes it ### Maintenance and backports -OpenShell maintains two minor release lines: the latest minor and N-1. Support +OpenShell maintains two release lines: the latest minor and N-1. Support applies to the newest patch on each line. Users on an older patch update to the new maintenance patch rather than receiving a separate fix for every historical patch. diff --git a/rfc/0014-release-stability/release-qualification.md b/rfc/0014-release-stability/release-qualification.md index dea912f8bd..b5fa456a4d 100644 --- a/rfc/0014-release-stability/release-qualification.md +++ b/rfc/0014-release-stability/release-qualification.md @@ -1,17 +1,17 @@ # RFC 0014 Supplement - Release Qualification A release candidate is eligible for stable release only after its published -artifacts pass every required [conformance](#conformance) and -[upgrade](#upgrade) workflow, its +artifacts pass every required [conformance test](#conformance-tests) and +[upgrade test](#upgrade-tests), its [breaking API change review](#breaking-api-change-review), and its [security review](#security-review). -## Conformance +## Conformance tests -Conformance runs for different OpenShell driver and host configurations. -Kubernetes runs once per supported gateway topology. Each workflow installs the -candidate in one representative environment and verifies the supported -OpenShell behavior for that driver and topology. +Conformance tests run for different OpenShell driver, gateway, and host +configurations. Each workflow installs the candidate in one representative +environment and verifies the supported OpenShell behavior for that +configuration. For each driver, the suite: @@ -44,16 +44,18 @@ additional workflows. | ID | Compute driver | Representative environment | Gateway configuration | | --- | --- | --- | --- | | C01 | Docker | Ubuntu x86_64 with Docker 28.0.4 | Local gateway; TLS and sandbox mTLS; credentials; CDI GPU when stable | -| C02 | Podman | Fedora x86_64 with Podman 5.x rootless and SELinux enforcing | Local gateway; TLS and sandbox mTLS; credentials; CDI GPU when stable | +| C02 | Podman | Fedora x86_64 with Podman 5.x rootless | Local gateway; TLS and sandbox mTLS; credentials; CDI GPU when stable | | C03 | MicroVM | Linux x86_64 with KVM and IOMMU | Local gateway; libkrun CPU; TLS and sandbox mTLS; QEMU/VFIO GPU when stable | | C04 | Kubernetes | Kubernetes 1.29 | Sidecar, three replicas; external PostgreSQL; Kubernetes Secrets; TLS and OIDC; GPU when stable | | C05 | Kubernetes | Kubernetes 1.29 | Combined, three replicas; external PostgreSQL; Kubernetes Secrets; TLS and OIDC; GPU when stable | +| C06 | Docker | Fedora x86_64 with Docker 28.0.4 and SELinux enforcing | Local gateway; TLS and sandbox mTLS; credentials | +| C07 | Kubernetes | Supported OpenShift release | Combined, three replicas; external PostgreSQL; Kubernetes Secrets; TLS and OIDC | -## Upgrade +## Upgrade tests -Upgrade runs once per supported product installation package. It verifies that -users can move from every supported source release to the candidate without -reinstalling or losing supported state. +Upgrade tests run once per supported product installation package. They verify +that users can move from every supported source release to the candidate +without reinstalling or losing supported state. For each installation package, the suite: @@ -88,13 +90,8 @@ any additional baseline required by the N-1 maintenance promise. The review: 1. Runs protobuf compatibility checks against the supported descriptor baselines. 2. Runs language-specific compatibility checks for generated and hand-written - SDK interfaces. -3. Classifies each detected change as stable, experimental, or development-only - and records the evidence in the qualification record. -4. Confirms that a patch release contains no breaking stable API change. -5. For an intentional breaking change in a minor release, confirms the required - project version, protobuf package revision where applicable, migration - guidance, release notes, and approval. + SDK or configuration interfaces. An agent may assess this using a breaking + API detection skill. Breaking API change review passes when no unaddressed breaking change affects a stable API baseline and every intentional minor-release break satisfies the @@ -102,17 +99,12 @@ versioning and migration requirements. ## Security review -Security review runs once per candidate and covers the complete candidate -artifact set. A designated security approver: +Security review runs once per candidate and will: -1. Reviews vulnerability, dependency, container, and infrastructure scan +1. Produce vulnerability, dependency, container, and infrastructure scan results for the candidate artifacts. -2. Reviews changes since the previous stable release to authentication, - authorization, policy enforcement, sandbox isolation, credentials, and any updated trust boundary. -3. Confirms that required penetration testing is current for the affected trust - boundaries. -4. Records the scope, evidence, findings, and disposition in the qualification - record. +2. Run an agent-based security scanner, such as Codex Security, against changes + since the previous stable release. Security review passes when no unresolved critical or high-severity finding affects a supported configuration. From 1194ef8a0b60a3945749ac7375087700a53d77b1 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 17 Aug 2026 08:59:43 -0700 Subject: [PATCH 13/18] docs(rfc): define API maturity and conformance opt-outs Signed-off-by: Drew Newberry --- rfc/0014-release-stability/README.md | 57 +++++++++++-------- .../release-qualification.md | 15 +++-- 2 files changed, 42 insertions(+), 30 deletions(-) diff --git a/rfc/0014-release-stability/README.md b/rfc/0014-release-stability/README.md index 7b71335a2f..2eaf309dfd 100644 --- a/rfc/0014-release-stability/README.md +++ b/rfc/0014-release-stability/README.md @@ -17,7 +17,7 @@ predictable release cycle for production users and ecosystem developers. We propose - Development releases for every commit to `main`, nightly release candidates, and qualified stable releases every Tuesday. -- Stable and experimental API maturity, compatibility and versioning +- Alpha, beta, and stable API maturity, compatibility, and versioning rules, and maintenance for the latest and N-1 minor release lines. - A release qualification pipeline covering conformance, upgrades, API changes, and security reviews across the supported release matrix. @@ -25,12 +25,12 @@ We propose ## Motivation The goal is to exit alpha without slowing OpenShell's development. Releases -should remain frequent and automated, and experimental APIs should be able to +should remain frequent and automated, and alpha and beta APIs should be able to evolve quickly enough to keep pace with the ecosystem. At the same time, users need stable interfaces they can confidently build on. Starting with `0.1.0`, OpenShell provides both: a defined compatibility contract -for stable interfaces and room to evolve experimental APIs and features. +for stable interfaces and room to evolve alpha and beta APIs and features. Releases are suitable for production use within the published support matrix only after passing conformance, upgrade, compatibility, artifact, and security checks. @@ -48,9 +48,7 @@ passes. OpenShell publishes a development release for every commit to `main`. Each development release identifies its source commit and artifact manifest, and the floating `dev` alias points to the newest one. Development releases enable all -development compilation flags and features. They are not qualification -evidence, are not supported deployment pins, and are not candidates for stable -promotion. +development compilation flags and features. OpenShell builds a release candidate nightly for the next expected stable release when `main` has changed and normal CI passes. After `0.1.1`, candidates @@ -68,26 +66,35 @@ the `0.x` series: ### API and feature maturity -The maturity of an API or feature is independent of the release that contains -it: - -| Maturity | API naming | Compatibility | -| --- | --- | --- | -| Stable | Stable protobuf packages such as `v1` or `v2` | Covered by the release compatibility contract | -| Experimental | Explicit unstable package such as `v1beta1` | May change with documented migration guidance | - -Every API and feature is stable or experimental, regardless of whether it -appears in stable, release candidate, or development artifacts. - -An evolving API may ship in a beta package such as `v1beta1`. It may change to -`v1beta2` in a patch release with release notes and migration guidance. -Graduation adds a stable `v1` package instead of renaming the beta package. +OpenShell uses the alpha, beta, and stable maturity levels defined by +[AIP-181](https://google.aip.dev/181) for public Protobuf definitions and their +corresponding SDK interfaces. Protobuf packages encode maturity in their +version name. SDKs use language-appropriate package, module, namespace, or +symbol naming to expose the same classification. + +| Maturity | Protobuf naming | SDK naming | Compatibility | +| --- | --- | --- | --- | +| Alpha | `v1alpha` or `v1alpha1` | Language-specific alpha package, module, namespace, or symbol | May change or be removed without notice | +| Beta | `v1beta` or `v1beta1` | Language-specific beta package, module, namespace, or symbol | Mostly stable; breaking changes require a documented transition period | +| Stable | `v1` or `v2` | Default stable package, module, namespace, or symbol | Covered by the release compatibility contract | + +Every API and feature is alpha, beta, or stable, regardless of whether it +appears in stable, release candidate, or development artifacts. Each SDK must +document its language-specific naming convention, and alpha or beta interfaces +must not appear to be stable. + +Alpha APIs are intended for rapid iteration. Beta APIs are considered complete +and ready for public testing. A breaking beta change creates a new package such +as `v1beta2` and provides release notes, migration guidance, and a documented +transition period. Graduation adds a stable `v1` package instead of renaming an +alpha or beta package in place. Unreleased features use named compile-time flags such as `unstable-`, collected under a `dev` compilation flag. Development releases enable them; stable releases and release candidates exclude them from service binaries, the CLI, -configuration, and documentation. For now, every SDK package may include their -generated types and client methods. +configuration, and documentation. For now, SDK distributions may include their +generated types and client methods when the SDK naming convention communicates +their maturity. ### Breaking changes and API versioning @@ -99,7 +106,7 @@ old protocol for a defined maintenance window or supplies an explicit migration A breaking CLI, SDK, configuration, policy, Helm, or state change requires a minor project release even when no protobuf package changes. Conversely, a -new experimental `v1beta2` package does not require a minor project release +new beta `v1beta2` package does not require a minor project release when it does not break any stable interface. Breaking-change detection runs during code review and again during release @@ -113,7 +120,7 @@ The following examples illustrate how these rules affect a release candidate: | Example | Concrete change | Release treatment | | --- | --- | --- | | Breaking stable Protobuf contract | `v1: string policy = 7` to `v2: PolicyReference policy = 7` | Blocks a patch RC; ships as `v2` in a minor release while `v1` remains supported. | -| Breaking experimental Python SDK method | `create_sandbox(timeout=30)` to `create_sandbox(deadline=...)` | May ship in a patch release with migration notes. | +| Breaking beta Python SDK method | `create_sandbox(timeout=30)` to `create_sandbox(deadline=...)` | May ship in a patch release after a documented transition period. | | Breaking stable policy document | `endpoints:` to `destinations:` | Blocks a patch RC unless both fields remain supported. | | Breaking stable CLI contract | `--policy policy.yaml` to `--policy-file policy.yaml` | Requires retaining the old flag as an alias or shipping a minor release. | @@ -185,7 +192,7 @@ the next Tuesday release. commit to `main` with all development features, and publish sequential `0.1.0-rc.N` candidates with the release feature set leading to 0.1.0. 2. **Make the necessary breaking API changes.** Use the pre-0.1.0 window to - finalize stable interfaces, move evolving APIs to experimental packages, + finalize stable interfaces, move evolving APIs to alpha or beta packages, and establish the compatibility baseline. 3. **Build qualification tests and release machinery.** Automate compatibility detection, conformance, upgrade, breaking API change review, security diff --git a/rfc/0014-release-stability/release-qualification.md b/rfc/0014-release-stability/release-qualification.md index b5fa456a4d..182295320d 100644 --- a/rfc/0014-release-stability/release-qualification.md +++ b/rfc/0014-release-stability/release-qualification.md @@ -29,11 +29,14 @@ For each driver, the suite: persisted resources are removed. Conformance passes only when every driver workflow completes without an -unexpected skip or retry-dependent result. A workflow may exercise relevant -GPU, authentication, credential-driver, interceptor, middleware, and -client/server skew variants as subcases without creating separate workflows. -Unsupported capabilities must return documented errors rather than fail -silently. +undeclared skip or retry-dependent result. A configuration may opt out of a +specific conformance test when it does not support the capability under test. +The opt-out and unsupported capability must be declared in the test +configuration before qualification runs; any other skip fails qualification. +A workflow may exercise relevant GPU, authentication, credential-driver, +interceptor, middleware, and client/server skew variants as subcases without +creating separate workflows. Unsupported capabilities must return documented +errors rather than fail silently. Each workflow uses one representative environment for the configuration under test. It may run multiple capability subcases inside that environment without creating @@ -41,6 +44,8 @@ additional workflows. ### Configurations to test +The goal is to provide test coverage for each documented driver, topology, and environment configuration. + | ID | Compute driver | Representative environment | Gateway configuration | | --- | --- | --- | --- | | C01 | Docker | Ubuntu x86_64 with Docker 28.0.4 | Local gateway; TLS and sandbox mTLS; credentials; CDI GPU when stable | From 1a87bac46e26874f8877b3d22f7b8878e020435f Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 17 Aug 2026 10:13:40 -0700 Subject: [PATCH 14/18] docs(rfc): adopt Preview and Stable API maturity Signed-off-by: Drew Newberry --- rfc/0014-release-stability/README.md | 58 ++++++++++++++-------------- 1 file changed, 28 insertions(+), 30 deletions(-) diff --git a/rfc/0014-release-stability/README.md b/rfc/0014-release-stability/README.md index 2eaf309dfd..b65229d916 100644 --- a/rfc/0014-release-stability/README.md +++ b/rfc/0014-release-stability/README.md @@ -17,7 +17,7 @@ predictable release cycle for production users and ecosystem developers. We propose - Development releases for every commit to `main`, nightly release candidates, and qualified stable releases every Tuesday. -- Alpha, beta, and stable API maturity, compatibility, and versioning +- Preview and Stable API maturity, compatibility, and versioning rules, and maintenance for the latest and N-1 minor release lines. - A release qualification pipeline covering conformance, upgrades, API changes, and security reviews across the supported release matrix. @@ -25,12 +25,12 @@ We propose ## Motivation The goal is to exit alpha without slowing OpenShell's development. Releases -should remain frequent and automated, and alpha and beta APIs should be able to +should remain frequent and automated, and Preview APIs should be able to evolve quickly enough to keep pace with the ecosystem. At the same time, users -need stable interfaces they can confidently build on. +need Stable interfaces they can confidently build on. Starting with `0.1.0`, OpenShell provides both: a defined compatibility contract -for stable interfaces and room to evolve alpha and beta APIs and features. +for Stable interfaces and room to evolve Preview APIs and features. Releases are suitable for production use within the published support matrix only after passing conformance, upgrade, compatibility, artifact, and security checks. @@ -66,28 +66,24 @@ the `0.x` series: ### API and feature maturity -OpenShell uses the alpha, beta, and stable maturity levels defined by -[AIP-181](https://google.aip.dev/181) for public Protobuf definitions and their -corresponding SDK interfaces. Protobuf packages encode maturity in their -version name. SDKs use language-appropriate package, module, namespace, or -symbol naming to expose the same classification. +OpenShell designates public Protobuf definitions and their corresponding SDK +interfaces as Preview or Stable. Protobuf packages encode the designation in +their version name. SDKs use language-appropriate package, module, namespace, +or symbol naming to expose the same designation. | Maturity | Protobuf naming | SDK naming | Compatibility | | --- | --- | --- | --- | -| Alpha | `v1alpha` or `v1alpha1` | Language-specific alpha package, module, namespace, or symbol | May change or be removed without notice | -| Beta | `v1beta` or `v1beta1` | Language-specific beta package, module, namespace, or symbol | Mostly stable; breaking changes require a documented transition period | -| Stable | `v1` or `v2` | Default stable package, module, namespace, or symbol | Covered by the release compatibility contract | +| Preview | `v1preview` or `v1preview1` | Language-specific Preview package, module, namespace, or symbol | May change or be removed in any release | +| Stable | `v1` or `v2` | Default Stable package, module, namespace, or symbol | Covered by the release compatibility contract | -Every API and feature is alpha, beta, or stable, regardless of whether it +Every API and feature is Preview or Stable, regardless of whether it appears in stable, release candidate, or development artifacts. Each SDK must -document its language-specific naming convention, and alpha or beta interfaces -must not appear to be stable. +document its language-specific naming convention, and Preview interfaces must +not appear to be Stable. -Alpha APIs are intended for rapid iteration. Beta APIs are considered complete -and ready for public testing. A breaking beta change creates a new package such -as `v1beta2` and provides release notes, migration guidance, and a documented -transition period. Graduation adds a stable `v1` package instead of renaming an -alpha or beta package in place. +Preview APIs are intended for public evaluation and rapid iteration. They may +change in place without a compatibility guarantee. Graduation adds a Stable +`v1` package instead of renaming the Preview package in place. Unreleased features use named compile-time flags such as `unstable-`, collected under a `dev` compilation flag. Development releases enable them; stable @@ -99,15 +95,17 @@ their maturity. ### Breaking changes and API versioning If a breaking change affects a stable OpenShell surface, the release moves to -the next minor version. If the same change is incompatible with a stable -protobuf contract, the protocol _may_ move to a new major-versioned package, +the next minor version. If the same change is incompatible with a Stable +protobuf contract, the protocol must move to a new major-versioned package, for example `openshell.v1` to `openshell.v2`. The supported server retains the -old protocol for a defined maintenance window or supplies an explicit migration path. +old protocol for a defined maintenance window and supplies an explicit migration path. -A breaking CLI, SDK, configuration, policy, Helm, or state change requires -a minor project release even when no protobuf package changes. Conversely, a -new beta `v1beta2` package does not require a minor project release -when it does not break any stable interface. +A breaking Stable SDK interface must move to a corresponding versioned SDK +surface and retain the old interface for the same maintenance window. A +breaking CLI, configuration, policy, Helm, or state change requires a minor +project release even when no Protobuf package changes. Conversely, a breaking +Preview API change does not require a minor project release when it does not +break any Stable interface. Breaking-change detection runs during code review and again during release candidate qualification. Stable protobuf packages use Buf's `FILE` rules @@ -119,8 +117,8 @@ The following examples illustrate how these rules affect a release candidate: | Example | Concrete change | Release treatment | | --- | --- | --- | -| Breaking stable Protobuf contract | `v1: string policy = 7` to `v2: PolicyReference policy = 7` | Blocks a patch RC; ships as `v2` in a minor release while `v1` remains supported. | -| Breaking beta Python SDK method | `create_sandbox(timeout=30)` to `create_sandbox(deadline=...)` | May ship in a patch release after a documented transition period. | +| Breaking Stable Protobuf contract | `string policy = 7` to `PolicyReference policy = 7` | Blocks a patch RC and requires a minor OpenShell release. | +| Breaking Preview Python SDK method | `create_sandbox(timeout=30)` to `create_sandbox(deadline=...)` | May ship in any release with release notes and migration guidance. | | Breaking stable policy document | `endpoints:` to `destinations:` | Blocks a patch RC unless both fields remain supported. | | Breaking stable CLI contract | `--policy policy.yaml` to `--policy-file policy.yaml` | Requires retaining the old flag as an alias or shipping a minor release. | @@ -192,7 +190,7 @@ the next Tuesday release. commit to `main` with all development features, and publish sequential `0.1.0-rc.N` candidates with the release feature set leading to 0.1.0. 2. **Make the necessary breaking API changes.** Use the pre-0.1.0 window to - finalize stable interfaces, move evolving APIs to alpha or beta packages, + finalize Stable interfaces, move evolving APIs to Preview packages, and establish the compatibility baseline. 3. **Build qualification tests and release machinery.** Automate compatibility detection, conformance, upgrade, breaking API change review, security From d5c5686ef9961bb4f3b922e3f8d3c54c988ca582 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 17 Aug 2026 11:40:38 -0700 Subject: [PATCH 15/18] docs(rfc): define Stable and Experimental APIs Signed-off-by: Drew Newberry --- rfc/0014-release-stability/README.md | 51 ++++++++++++---------------- 1 file changed, 22 insertions(+), 29 deletions(-) diff --git a/rfc/0014-release-stability/README.md b/rfc/0014-release-stability/README.md index b65229d916..f854454a40 100644 --- a/rfc/0014-release-stability/README.md +++ b/rfc/0014-release-stability/README.md @@ -17,7 +17,7 @@ predictable release cycle for production users and ecosystem developers. We propose - Development releases for every commit to `main`, nightly release candidates, and qualified stable releases every Tuesday. -- Preview and Stable API maturity, compatibility, and versioning +- Stable and Experimental API maturity, compatibility, and versioning rules, and maintenance for the latest and N-1 minor release lines. - A release qualification pipeline covering conformance, upgrades, API changes, and security reviews across the supported release matrix. @@ -25,12 +25,12 @@ We propose ## Motivation The goal is to exit alpha without slowing OpenShell's development. Releases -should remain frequent and automated, and Preview APIs should be able to +should remain frequent and automated, and Experimental APIs should be able to evolve quickly enough to keep pace with the ecosystem. At the same time, users need Stable interfaces they can confidently build on. Starting with `0.1.0`, OpenShell provides both: a defined compatibility contract -for Stable interfaces and room to evolve Preview APIs and features. +for Stable interfaces and room to evolve Experimental APIs and features. Releases are suitable for production use within the published support matrix only after passing conformance, upgrade, compatibility, artifact, and security checks. @@ -66,24 +66,24 @@ the `0.x` series: ### API and feature maturity -OpenShell designates public Protobuf definitions and their corresponding SDK -interfaces as Preview or Stable. Protobuf packages encode the designation in -their version name. SDKs use language-appropriate package, module, namespace, -or symbol naming to expose the same designation. +Public APIs are Stable by default. APIs that are expected to change frequently +must be explicitly designated Experimental. Protobuf packages encode the +designation in their version name. SDKs use language-appropriate package, +module, namespace, or symbol naming to expose the same designation. | Maturity | Protobuf naming | SDK naming | Compatibility | | --- | --- | --- | --- | -| Preview | `v1preview` or `v1preview1` | Language-specific Preview package, module, namespace, or symbol | May change or be removed in any release | -| Stable | `v1` or `v2` | Default Stable package, module, namespace, or symbol | Covered by the release compatibility contract | +| Stable | `v1` or `v2` | Default Stable package, module, namespace, or symbol | Backward-compatible across patch releases; may change in a minor release with notice and migration guidance | +| Experimental | `v1experimental` | Language-specific Experimental package, module, namespace, or symbol | May change or be removed in a patch release without notice | -Every API and feature is Preview or Stable, regardless of whether it +Every API and feature is Stable or Experimental, regardless of whether it appears in stable, release candidate, or development artifacts. Each SDK must -document its language-specific naming convention, and Preview interfaces must -not appear to be Stable. +document its language-specific naming convention, and Experimental interfaces +must not appear to be Stable. -Preview APIs are intended for public evaluation and rapid iteration. They may -change in place without a compatibility guarantee. Graduation adds a Stable -`v1` package instead of renaming the Preview package in place. +Experimental APIs are intended for rapid iteration and may change in place +without a compatibility guarantee. Graduation adds a Stable `v1` package +instead of renaming the Experimental package in place. Unreleased features use named compile-time flags such as `unstable-`, collected under a `dev` compilation flag. Development releases enable them; stable @@ -94,18 +94,11 @@ their maturity. ### Breaking changes and API versioning -If a breaking change affects a stable OpenShell surface, the release moves to -the next minor version. If the same change is incompatible with a Stable -protobuf contract, the protocol must move to a new major-versioned package, -for example `openshell.v1` to `openshell.v2`. The supported server retains the -old protocol for a defined maintenance window and supplies an explicit migration path. - -A breaking Stable SDK interface must move to a corresponding versioned SDK -surface and retain the old interface for the same maintenance window. A -breaking CLI, configuration, policy, Helm, or state change requires a minor -project release even when no Protobuf package changes. Conversely, a breaking -Preview API change does not require a minor project release when it does not -break any Stable interface. +A breaking change to a Stable API or other stable OpenShell surface requires a +minor release with notice and migration guidance. This applies to Protobuf, +SDK, CLI, configuration, policy, Helm, and state interfaces. A breaking +Experimental API change may ship in a patch release without notice when it does +not break a Stable interface. Breaking-change detection runs during code review and again during release candidate qualification. Stable protobuf packages use Buf's `FILE` rules @@ -118,7 +111,7 @@ The following examples illustrate how these rules affect a release candidate: | Example | Concrete change | Release treatment | | --- | --- | --- | | Breaking Stable Protobuf contract | `string policy = 7` to `PolicyReference policy = 7` | Blocks a patch RC and requires a minor OpenShell release. | -| Breaking Preview Python SDK method | `create_sandbox(timeout=30)` to `create_sandbox(deadline=...)` | May ship in any release with release notes and migration guidance. | +| Breaking Experimental Python SDK method | `create_sandbox(timeout=30)` to `create_sandbox(deadline=...)` | May ship in a patch release without notice. | | Breaking stable policy document | `endpoints:` to `destinations:` | Blocks a patch RC unless both fields remain supported. | | Breaking stable CLI contract | `--policy policy.yaml` to `--policy-file policy.yaml` | Requires retaining the old flag as an alias or shipping a minor release. | @@ -190,7 +183,7 @@ the next Tuesday release. commit to `main` with all development features, and publish sequential `0.1.0-rc.N` candidates with the release feature set leading to 0.1.0. 2. **Make the necessary breaking API changes.** Use the pre-0.1.0 window to - finalize Stable interfaces, move evolving APIs to Preview packages, + finalize Stable interfaces, move evolving APIs to Experimental packages, and establish the compatibility baseline. 3. **Build qualification tests and release machinery.** Automate compatibility detection, conformance, upgrade, breaking API change review, security From 17936a2831316723eeff765a2db6ca4845e3f5f8 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 17 Aug 2026 12:14:24 -0700 Subject: [PATCH 16/18] docs(rfc): allow feature-driven minor releases Signed-off-by: Drew Newberry --- rfc/0014-release-stability/README.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/rfc/0014-release-stability/README.md b/rfc/0014-release-stability/README.md index f854454a40..7e54ad4b5e 100644 --- a/rfc/0014-release-stability/README.md +++ b/rfc/0014-release-stability/README.md @@ -41,9 +41,10 @@ checks. Starting with `0.1.0`, OpenShell publishes stable tagged releases intended for production use within the published support matrix. Stable releases occur every Tuesday and increment -the patch version, for example `0.1.1` followed by `0.1.2`. A stable tag is -published only when there are changes and every blocking qualification suite -passes. +the patch version by default, for example `0.1.1` followed by `0.1.2`. A release +may instead increment the minor version when it introduces notable new features +or documented breaking changes. A stable tag is published only when there are +changes and every blocking qualification suite passes. OpenShell publishes a development release for every commit to `main`. Each development release identifies its source commit and artifact manifest, and the @@ -61,8 +62,9 @@ the `0.x` series: - Patch releases may contain bug fixes and additive, backward-compatible functionality. They do not intentionally break a stable interface. -- An unavoidable breaking change to any stable interface starts a new minor - release and resets the patch version, for example `0.1.x` to `0.2.0`. +- Minor releases may represent notable new features even when they remain + backward-compatible. They may also contain documented breaking changes to + stable interfaces, for example `0.1.x` to `0.2.0`. ### API and feature maturity From 2cfacddd61f8e7b47a288e8b6769f42874900089 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Tue, 18 Aug 2026 19:01:34 -0700 Subject: [PATCH 17/18] docs(rfc): clarify release build audiences Signed-off-by: Drew Newberry --- rfc/0014-release-stability/README.md | 34 ++++++++++++-- .../release-version-selection.md | 46 +++++++++++++++++++ 2 files changed, 77 insertions(+), 3 deletions(-) create mode 100644 rfc/0014-release-stability/release-version-selection.md diff --git a/rfc/0014-release-stability/README.md b/rfc/0014-release-stability/README.md index 7e54ad4b5e..ae3101141e 100644 --- a/rfc/0014-release-stability/README.md +++ b/rfc/0014-release-stability/README.md @@ -49,12 +49,31 @@ changes and every blocking qualification suite passes. OpenShell publishes a development release for every commit to `main`. Each development release identifies its source commit and artifact manifest, and the floating `dev` alias points to the newest one. Development releases enable all -development compilation flags and features. +development compilation flags and features. They give feature authors, early +adopters, and integration owners a way to consume upcoming OpenShell changes +between stable releases. This also allows development of a large feature to +span multiple weeks behind a compile-time feature flag without including the +unfinished feature in the stable release track. Development releases have +passed normal CI, but have not passed release qualification and are not +intended for production use. OpenShell builds a release candidate nightly for the next expected stable release when `main` has changed and normal CI passes. After `0.1.1`, candidates are numbered `0.1.2-rc.1`, `0.1.2-rc.2`, and so on. A release candidate is promoted to a stable release tag as part of the weekly release pipeline once the candidate has passed qualification. +Release candidates give the automated release qualification and QA systems an +immutable artifact set to evaluate. They are also available to maintainers and +integration owners who need to validate the prospective stable release. An RC +uses the same release feature set as stable and may still fail qualification; +it is not intended for production use. A new RC is built nightly when eligible +changes are available so failures can be fixed and reevaluated before Tuesday. + +| Release | Intended users | Contents and expectations | +| --- | --- | --- | +| Development | Feature authors, early adopters, and integration owners testing upcoming functionality | Published for every commit to `main`; enables development features; passes normal CI but not release qualification | +| Release candidate | Automated qualification, maintainers, and integration owners validating the next stable release | Built nightly from eligible `main`; uses the stable feature set; immutable but not yet qualified for production | +| Stable | Production users and downstream integrations that require the published compatibility and support contract | Published Tuesday by promoting an RC that passed every blocking qualification suite | + ### Project version and compatibility contract Version `0.1.0` begins OpenShell's supported compatibility contract. For @@ -66,6 +85,10 @@ the `0.x` series: backward-compatible. They may also contain documented breaking changes to stable interfaces, for example `0.1.x` to `0.2.0`. +The [release version selection supplement](release-version-selection.md) +defines how Conventional Commits select the next patch or minor release +candidate. + ### API and feature maturity Public APIs are Stable by default. APIs that are expected to change frequently @@ -125,12 +148,12 @@ publication: ```mermaid flowchart LR A["Commit to main"] --> B["Dev release
dev features enabled"] - A --> C["Qualified main commit"] + A --> C["Normal CI passes"] C --> D["Nightly RC build
release feature set"] D --> E["RC qualification"] E -->|"pass"| F["Eligible Tuesday candidate"] E -->|"fail"| G["No stable release"] - F --> H["Build or promote stable artifacts"] + F --> H["Promote exact RC artifacts"] H --> I["Final artifact checks"] I -->|"pass"| J["Create tag and publish"] I -->|"fail"| G @@ -140,6 +163,11 @@ Every release candidate produces a manifest containing its version, full source commit, build inputs, artifact names and digests, SBOM and provenance references, and qualification results. Qualification installs and exercises the candidate artifacts wherever practical rather than substituting a source build. +The candidate manifest carries the RC identifier so promotable binaries and +content-addressable artifacts can be built with the prospective stable version. +Once qualification begins, an RC is immutable: any source, dependency, build +input, or artifact change creates a new RC. Stable publication adds the stable +release references to the qualified artifacts without recompiling them. Release qualification consists of four suites defined in the [release qualification supplement](release-qualification.md): diff --git a/rfc/0014-release-stability/release-version-selection.md b/rfc/0014-release-stability/release-version-selection.md new file mode 100644 index 0000000000..01c9274d61 --- /dev/null +++ b/rfc/0014-release-stability/release-version-selection.md @@ -0,0 +1,46 @@ +# RFC 0014 Supplement - Release Version Selection + +This supplement defines how OpenShell selects the next release candidate +version after a stable release during the `0.x` series. + +## Algorithm + +1. Find the latest stable tag and collect commits after it on the target branch. +2. Classify commits using Conventional Commits: + - `feat:` requests a minor release. + - A commit marked with `!` or a `BREAKING CHANGE` footer requests a minor + release during `0.x`. + - `fix:` and `deps:` request a patch release. + - Other commit types do not request a release by default. +3. Select the highest requested bump. Minor takes precedence over patch. If no + commit requests a release, do not create a release candidate. +4. Increment the stable version to obtain the candidate base version. From + `0.2.0`, a patch becomes `0.2.1` and a minor becomes `0.3.0`. +5. Publish `-rc.1` for a new base version. If that base already has a release + candidate, increment the RC number instead. +6. Fail the branch check if the candidate base version is not greater than the + latest stable version. + +| Latest stable | Commits since stable | Next candidate | +| --- | --- | --- | +| `0.2.0` | `fix:` | `0.2.1-rc.1` | +| `0.2.0` | `feat:` | `0.3.0-rc.1` | +| `0.2.0` | `feat!:` | `0.3.0-rc.1` | +| `0.2.0` | Only `docs:` or `chore:` | No candidate | + +## Release Please + +[Release Please](https://github.com/googleapis/release-please-action) can +implement the commit classification and base-version calculation. During +`0.x`, its manifest configuration should include: + +```json +{ + "bump-minor-pre-major": true, + "bump-patch-for-minor-pre-major": false +} +``` + +The release workflow owns the `-rc.N` suffix and stable promotion. An explicit +`Release-As: x.y.z` footer may override the calculation with maintainer +approval. From a3dde4a942944c3702f7f543cc64494bd15ed15f Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Wed, 19 Aug 2026 10:51:40 -0700 Subject: [PATCH 18/18] docs(rfc): define pre-release train semantics Signed-off-by: Drew Newberry --- rfc/0014-release-stability/README.md | 85 ++++++++++--------- rfc/0014-release-stability/build-matrix.md | 2 +- .../release-qualification.md | 30 +++---- .../release-version-selection.md | 35 +++++--- 4 files changed, 82 insertions(+), 70 deletions(-) diff --git a/rfc/0014-release-stability/README.md b/rfc/0014-release-stability/README.md index ae3101141e..3df68ba5fc 100644 --- a/rfc/0014-release-stability/README.md +++ b/rfc/0014-release-stability/README.md @@ -16,7 +16,8 @@ predictable release cycle for production users and ecosystem developers. We propose -- Development releases for every commit to `main`, nightly release candidates, and qualified stable releases every Tuesday. +- Development releases for every commit to `main`, nightly pre-releases, and + qualified stable releases every Tuesday. - Stable and Experimental API maturity, compatibility, and versioning rules, and maintenance for the latest and N-1 minor release lines. - A release qualification pipeline covering conformance, upgrades, @@ -57,22 +58,25 @@ unfinished feature in the stable release track. Development releases have passed normal CI, but have not passed release qualification and are not intended for production use. -OpenShell builds a release candidate nightly for the next expected stable -release when `main` has changed and normal CI passes. After `0.1.1`, candidates -are numbered `0.1.2-rc.1`, `0.1.2-rc.2`, and so on. A release candidate is promoted to a stable release tag as part of the weekly release pipeline once the candidate has passed qualification. +OpenShell builds a pre-release nightly for the next expected stable release +when `main` has changed and normal CI passes. After `0.1.1`, pre-releases are +numbered `0.1.2-pre.1`, `0.1.2-pre.2`, and so on. Features may land between +pre-releases. The first pre-release locks the version for that weekly release +train. Once a patch train starts, breaking changes that require a minor release +are staged for the following week; the train never switches from patch to minor. -Release candidates give the automated release qualification and QA systems an +Pre-releases give the automated release qualification and QA systems an immutable artifact set to evaluate. They are also available to maintainers and -integration owners who need to validate the prospective stable release. An RC -uses the same release feature set as stable and may still fail qualification; -it is not intended for production use. A new RC is built nightly when eligible -changes are available so failures can be fixed and reevaluated before Tuesday. +integration owners who need to validate the prospective stable release. A +pre-release uses the same release feature set as stable and may still fail +qualification; it is not intended for production use. Building one nightly +allows failures to be fixed and reevaluated before Tuesday. | Release | Intended users | Contents and expectations | | --- | --- | --- | | Development | Feature authors, early adopters, and integration owners testing upcoming functionality | Published for every commit to `main`; enables development features; passes normal CI but not release qualification | -| Release candidate | Automated qualification, maintainers, and integration owners validating the next stable release | Built nightly from eligible `main`; uses the stable feature set; immutable but not yet qualified for production | -| Stable | Production users and downstream integrations that require the published compatibility and support contract | Published Tuesday by promoting an RC that passed every blocking qualification suite | +| Pre-release | Automated qualification, maintainers, and integration owners validating the next stable release | Built nightly from eligible `main`; uses the stable feature set; immutable but not yet qualified for production | +| Stable | Production users and downstream integrations that require the published compatibility and support contract | Published Tuesday from a pre-release that passed every blocking qualification suite | ### Project version and compatibility contract @@ -87,7 +91,7 @@ the `0.x` series: The [release version selection supplement](release-version-selection.md) defines how Conventional Commits select the next patch or minor release -candidate. +pre-release. ### API and feature maturity @@ -102,7 +106,7 @@ module, namespace, or symbol naming to expose the same designation. | Experimental | `v1experimental` | Language-specific Experimental package, module, namespace, or symbol | May change or be removed in a patch release without notice | Every API and feature is Stable or Experimental, regardless of whether it -appears in stable, release candidate, or development artifacts. Each SDK must +appears in stable, pre-release, or development artifacts. Each SDK must document its language-specific naming convention, and Experimental interfaces must not appear to be Stable. @@ -112,7 +116,7 @@ instead of renaming the Experimental package in place. Unreleased features use named compile-time flags such as `unstable-`, collected under a `dev` compilation flag. Development releases enable them; stable -releases and release candidates exclude them from service binaries, the CLI, +releases and pre-releases exclude them from service binaries, the CLI, configuration, and documentation. For now, SDK distributions may include their generated types and client methods when the SDK naming convention communicates their maturity. @@ -125,49 +129,47 @@ SDK, CLI, configuration, policy, Helm, and state interfaces. A breaking Experimental API change may ship in a patch release without notice when it does not break a Stable interface. -Breaking-change detection runs during code review and again during release -candidate qualification. Stable protobuf packages use Buf's `FILE` rules +Breaking-change detection runs during code review and again during pre-release +qualification. Stable protobuf packages use Buf's `FILE` rules against the latest stable baseline and any additional supported baseline needed for the N-1 maintenance promise. Language-specific API checks or agent review skills cover the public SDKs. -The following examples illustrate how these rules affect a release candidate: +The following examples illustrate how these rules affect a pre-release: | Example | Concrete change | Release treatment | | --- | --- | --- | -| Breaking Stable Protobuf contract | `string policy = 7` to `PolicyReference policy = 7` | Blocks a patch RC and requires a minor OpenShell release. | +| Breaking Stable Protobuf contract | `string policy = 7` to `PolicyReference policy = 7` | Blocks a patch release and requires a minor OpenShell release. | | Breaking Experimental Python SDK method | `create_sandbox(timeout=30)` to `create_sandbox(deadline=...)` | May ship in a patch release without notice. | -| Breaking stable policy document | `endpoints:` to `destinations:` | Blocks a patch RC unless both fields remain supported. | +| Breaking stable policy document | `endpoints:` to `destinations:` | Blocks a patch release unless both fields remain supported. | | Breaking stable CLI contract | `--policy policy.yaml` to `--policy-file policy.yaml` | Requires retaining the old flag as an alias or shipping a minor release. | -### Release candidate qualification and stable release promotion +### Pre-release qualification and stable publication -The release system separates candidate creation, qualification, and stable +The release system separates pre-release creation, qualification, and stable publication: ```mermaid flowchart LR A["Commit to main"] --> B["Dev release
dev features enabled"] A --> C["Normal CI passes"] - C --> D["Nightly RC build
release feature set"] - D --> E["RC qualification"] - E -->|"pass"| F["Eligible Tuesday candidate"] + C --> D["Tag and build nightly pre-release
release feature set"] + D --> E["Pre-release qualification"] + E -->|"pass"| F["Eligible Tuesday pre-release"] E -->|"fail"| G["No stable release"] - F --> H["Promote exact RC artifacts"] + F --> H["Publish stable artifacts"] H --> I["Final artifact checks"] I -->|"pass"| J["Create tag and publish"] I -->|"fail"| G ``` -Every release candidate produces a manifest containing its version, -full source commit, build inputs, artifact names and digests, SBOM and provenance -references, and qualification results. Qualification installs and exercises the -candidate artifacts wherever practical rather than substituting a source build. -The candidate manifest carries the RC identifier so promotable binaries and -content-addressable artifacts can be built with the prospective stable version. -Once qualification begins, an RC is immutable: any source, dependency, build -input, or artifact change creates a new RC. Stable publication adds the stable -release references to the qualified artifacts without recompiling them. +Every pre-release is tagged before qualification and produces a manifest with +its version, source commit, build inputs, artifact digests, SBOM, provenance, +and qualification results. Qualification exercises those artifacts rather than +a substitute source build. Pre-releases are stored in artifact storage instead +of published as GitHub Releases, following the +[Bazel rolling release model](https://bazel.build/release/rolling). Any change +creates a new pre-release. Release qualification consists of four suites defined in the [release qualification supplement](release-qualification.md): @@ -177,9 +179,9 @@ Release qualification consists of four suites defined in the - **Upgrade** runs once per supported installation package and verifies its upgrade path, state migration, post-upgrade health, and rollback where promised. -- **Breaking API change review** runs once per candidate and compares stable +- **Breaking API change review** runs once per pre-release and compares stable protobuf and SDK interfaces with every applicable compatibility baseline. -- **Security review** runs once per candidate and verifies security scan +- **Security review** runs once per pre-release and verifies security scan results, reviews changes to security-sensitive boundaries, and confirms that every finding has the required disposition. @@ -187,7 +189,8 @@ The initial release targets are defined in the [build matrix](build-matrix.md), and blocking coverage is defined in the [release qualification supplement](release-qualification.md). -The weekly release selects the newest eligible release candidate and promotes it to the next stable release. +The weekly release tags the newest eligible pre-release commit with the next +stable version and publishes the stable artifacts. ### Maintenance and backports @@ -209,14 +212,14 @@ the next Tuesday release. ## Implementation plan -1. **Keep per-commit dev releases and build 0.1.0 RCs nightly.** Build every - commit to `main` with all development features, and publish sequential - `0.1.0-rc.N` candidates with the release feature set leading to 0.1.0. +1. **Keep per-commit dev releases and build 0.1.0 pre-releases nightly.** Build + every commit to `main` with all development features, and publish sequential + `0.1.0-pre.N` artifacts with the release feature set leading to 0.1.0. 2. **Make the necessary breaking API changes.** Use the pre-0.1.0 window to finalize Stable interfaces, move evolving APIs to Experimental packages, and establish the compatibility baseline. 3. **Build qualification tests and release machinery.** Automate compatibility detection, conformance, upgrade, breaking API change review, security qualification, artifact validation, and release publication gates. -4. **Release 0.1.0.** Promote a qualified release candidate, publish the stable +4. **Release 0.1.0.** Select a qualified pre-release, publish the stable artifacts and support guidance, and begin the weekly release cadence. diff --git a/rfc/0014-release-stability/build-matrix.md b/rfc/0014-release-stability/build-matrix.md index 826a0f6791..43ca9f768e 100644 --- a/rfc/0014-release-stability/build-matrix.md +++ b/rfc/0014-release-stability/build-matrix.md @@ -12,7 +12,7 @@ topology, and capability is supported. The minimal blocking release gate. It contains one conformance workflow per compute driver, one Kubernetes conformance workflow per supported gateway topology, and one upgrade workflow per installation package, plus one breaking API change -review and one security review per candidate. Other supported dimensions are +review and one security review per pre-release. Other supported dimensions are exercised as subcases or separate CI controls rather than as a Cartesian product of release jobs. diff --git a/rfc/0014-release-stability/release-qualification.md b/rfc/0014-release-stability/release-qualification.md index 182295320d..243f6468df 100644 --- a/rfc/0014-release-stability/release-qualification.md +++ b/rfc/0014-release-stability/release-qualification.md @@ -1,7 +1,7 @@ # RFC 0014 Supplement - Release Qualification -A release candidate is eligible for stable release only after its published -artifacts pass every required [conformance test](#conformance-tests) and +A pre-release is eligible for stable publication only after its artifacts pass +every required [conformance test](#conformance-tests) and [upgrade test](#upgrade-tests), its [breaking API change review](#breaking-api-change-review), and its [security review](#security-review). @@ -9,13 +9,13 @@ artifacts pass every required [conformance test](#conformance-tests) and ## Conformance tests Conformance tests run for different OpenShell driver, gateway, and host -configurations. Each workflow installs the candidate in one representative +configurations. Each workflow installs the pre-release in one representative environment and verifies the supported OpenShell behavior for that configuration. For each driver, the suite: -1. Installs the candidate artifacts and starts the gateway and selected runtime. +1. Installs the pre-release artifacts and starts the gateway and selected runtime. 2. Verifies gateway health, version reporting, TLS, authentication, and authorization. 3. Creates a sandbox, connects to it, executes commands, and exercises stop, @@ -59,7 +59,7 @@ The goal is to provide test coverage for each documented driver, topology, and e ## Upgrade tests Upgrade tests run once per supported product installation package. They verify -that users can move from every supported source release to the candidate +that users can move from every supported source release to the pre-release without reinstalling or losing supported state. For each installation package, the suite: @@ -67,7 +67,7 @@ For each installation package, the suite: 1. Installs the source release and creates representative gateways, sandboxes, policies, providers, credentials, and persisted state. 2. Exercises the source installation to establish a known-good baseline. -3. Performs the documented in-place upgrade using the published candidate +3. Performs the documented in-place upgrade using the pre-release artifacts. 4. Verifies schema and state migrations, gateway health, existing resources, policy behavior, and new sandbox creation. @@ -79,16 +79,16 @@ For each installation package, the suite: | ID | Installation package | Representative environment | Drivers | Upgrade path | | --- | --- | --- | --- | --- | -| U01 | Homebrew formula | macOS on Apple Silicon | MicroVM | Previous stable formula to candidate formula | -| U02 | DEB through APT | Ubuntu x86_64 | Docker | Previous stable repository package to candidate package | -| U03 | RPM | Fedora x86_64 | Podman | Previous stable repository package to candidate package | -| U04 | Snap | Ubuntu x86_64 | Docker | Previous stable revision to candidate revision | -| U05 | Windows MSI through WinGet | Windows x86_64 | Docker Desktop | Previous stable MSI to candidate MSI | -| U06 | Helm chart | Kubernetes 1.29 | Kubernetes | Previous stable chart and images to candidate chart and image digests | +| U01 | Homebrew formula | macOS on Apple Silicon | MicroVM | Previous stable formula to pre-release formula | +| U02 | DEB through APT | Ubuntu x86_64 | Docker | Previous stable repository package to pre-release package | +| U03 | RPM | Fedora x86_64 | Podman | Previous stable repository package to pre-release package | +| U04 | Snap | Ubuntu x86_64 | Docker | Previous stable revision to pre-release revision | +| U05 | Windows MSI through WinGet | Windows x86_64 | Docker Desktop | Previous stable MSI to pre-release MSI | +| U06 | Helm chart | Kubernetes 1.29 | Kubernetes | Previous stable chart and images to pre-release chart and image digests | ## Breaking API change review -Breaking API change review runs once per candidate. It compares the candidate's +Breaking API change review runs once per pre-release. It compares its stable protobuf and public SDK interfaces with the latest stable baseline and any additional baseline required by the N-1 maintenance promise. The review: @@ -104,10 +104,10 @@ versioning and migration requirements. ## Security review -Security review runs once per candidate and will: +Security review runs once per pre-release and will: 1. Produce vulnerability, dependency, container, and infrastructure scan - results for the candidate artifacts. + results for the pre-release artifacts. 2. Run an agent-based security scanner, such as Codex Security, against changes since the previous stable release. diff --git a/rfc/0014-release-stability/release-version-selection.md b/rfc/0014-release-stability/release-version-selection.md index 01c9274d61..d21c8d9211 100644 --- a/rfc/0014-release-stability/release-version-selection.md +++ b/rfc/0014-release-stability/release-version-selection.md @@ -1,7 +1,7 @@ # RFC 0014 Supplement - Release Version Selection -This supplement defines how OpenShell selects the next release candidate -version after a stable release during the `0.x` series. +This supplement defines how OpenShell selects the next pre-release version +after a stable release during the `0.x` series. ## Algorithm @@ -13,20 +13,29 @@ version after a stable release during the `0.x` series. - `fix:` and `deps:` request a patch release. - Other commit types do not request a release by default. 3. Select the highest requested bump. Minor takes precedence over patch. If no - commit requests a release, do not create a release candidate. -4. Increment the stable version to obtain the candidate base version. From + commit requests a release, do not create a pre-release. +4. Increment the stable version to obtain the pre-release base version. From `0.2.0`, a patch becomes `0.2.1` and a minor becomes `0.3.0`. -5. Publish `-rc.1` for a new base version. If that base already has a release - candidate, increment the RC number instead. -6. Fail the branch check if the candidate base version is not greater than the +5. Create a `-pre.1` Git tag before building and qualifying a new base version. + If that base already has a pre-release, increment the pre-release number. +6. Treat that base version as fixed for the weekly train. If a patch train has + started, stage any later breaking change that requires a minor release for + the following week's train. +7. Fail the branch check if the pre-release base version is not greater than the latest stable version. -| Latest stable | Commits since stable | Next candidate | +| Latest stable | Commits since stable | Next pre-release | | --- | --- | --- | -| `0.2.0` | `fix:` | `0.2.1-rc.1` | -| `0.2.0` | `feat:` | `0.3.0-rc.1` | -| `0.2.0` | `feat!:` | `0.3.0-rc.1` | -| `0.2.0` | Only `docs:` or `chore:` | No candidate | +| `0.2.0` | `fix:` | `0.2.1-pre.1` | +| `0.2.0` | `feat:` | `0.3.0-pre.1` | +| `0.2.0` | `feat!:` | `0.3.0-pre.1` | +| `0.2.0` | Only `docs:` or `chore:` | No pre-release | + +Git tags are the version source of truth; release versions are never committed +to source. If a commit has multiple tags, select stable over pre-release, then +use Semantic Version order; use the commit SHA when neither exists. After +tagging the selected commit with its stable version, delete its `-pre.N` tags. +Stored pre-release artifacts retain their provenance metadata. ## Release Please @@ -41,6 +50,6 @@ implement the commit classification and base-version calculation. During } ``` -The release workflow owns the `-rc.N` suffix and stable promotion. An explicit +The release workflow owns the `-pre.N` suffix and stable publication. An explicit `Release-As: x.y.z` footer may override the calculation with maintainer approval.