docs(rfc): define stable release policy

[drew]

Summary

Propose RFC 0014, defining OpenShell's alpha exit criteria and the stable release policy for per-commit development builds, nightly-generated release candidates, and weekly stable releases.

Related Issue

Supersedes #2148. RFC 0014 consolidates that earlier support-matrix and API-compatibility proposal into the broader release-stability design.

Changes

• Define the Tuesday stable cadence, per-commit development releases, nightly-generated release candidates, and artifact promotion rules.
• Establish compatibility, capability maturity, maintenance, and backport policies.
• Define the build matrix and blocking conformance, upgrade, breaking API change, and security qualification suites.
• Require canonical binary payloads across standalone downloads, installation packages, and container images.

Testing

• mise run pre-commit passes
• Unit tests added/updated (documentation-only change)
• E2E tests added/updated (not applicable)

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (not applicable; this PR proposes an RFC)

[krishicks]

I left some questions inline. I'm wondering who the different release artifacts are for; who should use a release candidate, and why? What expectations should they have with such a release?

I think it may be implied what each release (dev, rc, release) might be for, but it would probably be good to make it explicit: who should use them, what expectations can they have about them.

There are also two candidates: the RC candidate (unqualified main?) and then the RC itself, since every commit becomes a dev release but only some get promoted to RCs following qualification on main (I guess? since the dev release is a branch off of commit to main in the diagram?).

I feel like breaking API change review needs to happen earlier in the cycle, because it also informs the version. If I get to 0.1.2-rc.2 and there's a breaking change, that should then become 0.1.3-rc.0, or something (what happens to 0.1.2 final, then?). It's not clear to me what should happen if a breaking API change is detected when in the process of qualifying a release candidate which intends to make that breaking API change and is marked as such. Possibly the same with security review; it feels like security qualification should be an rc prerequisite (and this relates to expectations a user should have about an rc.)

[SDAChess]

Overall, I’m positive on the RFC. The main part I’m unsure about is the RC naming and lifecycle.

If we publish rc.1, rc.2, and so on throughout the week, but only something like rc.6 can become Tuesday’s release, then most of those artifacts feel more like nightlies than actual release candidates.

I would prefer a model like this:

• Publish a date-tagged nightly build containing all development flags.
• Run the full conformance and qualification suites against every nightly. This gives us continuous feedback and allows us to catch release-blocking problems throughout the week rather than discovering them on Tuesday.
• On Tuesday, select a known-good commit and build the actual release artifact set as v0.1.2-rc.1, without development-only features.
• Run the qualification suites against those exact RC artifacts as the final release gate.
• If the RC passes, promote the same artifacts to v0.1.2. If it fails, fix the problems and cut v0.1.2-rc.2; the stable release waits.

This makes the intent of each artifact clearer: nightlies are continuously qualified development snapshots, while every RC is genuinely a candidate that could become the stable release unchanged. My two cents.

[drew]

@SDAChess recapping our review

• we'll rename rc to pre, eg 0.1.0-pre.1. we chose pre release over rc to make it clear that features may land between these builds
• pre releases aren't published as a github release, but instead published to either object storage, or github artifacts (need to figure out if this works). similar to https://bazel.build/release/rolling
• each pre-release is tagged before qualification. when the stable release is cut, the pre-release tags for that stable release are removed. pre-release artifacts in object storage continue to carry metadata about the provenance of that release.
• git tags are system of record when looking up what the next tag is. we never create commits that include stamped tags. version precedence stable git tag > pre release tag > sha. semver sorting is used to deconflict versions when multiple tags are on the same commit.