Vord

Enhancement Proposal

Proposal: The release plan — versions, artifacts, and support per milestone

The implementation arc (proposal 0001) orders the work and names two release points, but never says what a release is: which version a milestone cuts, what artifacts it comprises, how the token format's v0→v1 stamping (ADR-0003) interacts with 1.0, and what support an operator may rely on. This proposal maps releases onto the arc. It inherits the arc's one rule about time: the sequence is the commitment; there are no dates.

Motivation

Without a stated plan, releases get invented under announcement pressure — the moment most likely to produce a dishonest version number or an unsigned artifact. Fixing the policy now costs a page; it makes every milestone cut mechanical, keeps the ★ announcements honest about what is and is not promised, and gives operators the compatibility contract they need before they will run an identity system at all.

Design

  1. Every milestone cuts a tagged release; the number follows SemVer against the public contracts, never milestone prestige. The versioned contracts are: the wire formats (the specs/, versioned independently per ADR-0003), the OIDC/protocol surface and admin API (ADR-0014, ADR-0021), the config schema (validated by the ADR-0039 gate), the event schemas (ADR-0022), and the directory schema version (ADR-0011). A release that breaks none of them is a minor, whatever its marketing weight — the announcement is decoupled from the digit (decision 3).

  2. The version map.

    Milestone Cut Nature
    Prerequisite (specs) — no release; the specs version themselves (v0, unstable)
    M0 walking skeleton 0.1.0 tagged proof-of-concept; explicitly not deployable
    M1 keys / M2 revocation / M3 authz 0.2.0 / 0.3.0 / 0.4.0 soft stopping points, tagged, unsupported; 0.x minors may break anything (the Cargo 0.x convention, stated rather than assumed)
    M4 ★ 1.0.0-rc.n → 1.0.0 the first supported release (decision 4)
    M5 / M6 / M7 1.1.0 / 1.2.0 / 1.3.0 minors; additive by the gate-vs-era discipline of proposal 0001
    M8 ★ next minor — or 2.0.0 only if a public contract breaks the global-substrate announcement; the digit stays honest

  3. 1.0.0 is gated on format graduation. ADR-0003 stamps the token and status-list specs stable on "a second independent verifier **or a sustained conformance run"; the M4 definition of done already includes the OIDC conformance suite (V8), which is that sustained run. The release-candidate window at M4 exists precisely to satisfy it: 1.0.0-rc.n soaks under the continuously-running conformance and DST suites, and 1.0.0 ships with the specs stamped v1 — a 1.0 whose format may still change would be a false promise, so the two graduate together or 1.0 waits.

  4. What a release comprises (the artifact set, produced only by the proposal 0005 pipeline — signed, SBOM'd, provenance-attested; never built on a laptop):

    • the single static binary per supported platform (the dev/eval profile, ADR-0024) — from 0.1.0;
    • container images for the multi-node profiles — from 1.0.0-rc;
    • crates.io publication of the vord-* workspace crates (one lock-stepped workspace version) — begins once the ADR-0001 name check clears, at 0.1.0 or the first tag after;
    • checksums, signatures, and release notes generated from the milestone's tracking issues; the conformance-run and DST-suite results linked from the notes (the evidence, not just the claim).

    Separately-versioned artifacts ride their own trains against a compatibility matrix in the release notes: the SDKs (proposal 0027), the authenticator app (proposal 0028), and the specs themselves.

  5. Patch releases exist for one reason. x.y.Z carries security and critical-defect fixes only — cut from the release branch on demand, on the disclosure timeline (SECURITY.md, ADR-0027), never feature-bearing. Every security patch lands its regression test first (ADR-0028's rule), then the tag.

  6. The support promise is honest about project maturity. Pre-1.0: no support, latest tag only. From 1.0.0: security backports to the latest minor only — a truthful solo-maintainer promise, stated instead of implied. The window widens (N−1, then N−2) when a concrete operational owner commits, which is already Step 3's precondition (proposal 0001) — the support policy and the arc share the same trigger. MSRV bumps and dependency-major updates ride minors and are named in the notes.

  7. Deprecation discipline. A public-contract feature deprecated in minor N is removed no earlier than the next major, with the deprecation named in release notes and (where protocol-visible) in discovery metadata. The one exemption is security-forced removal, which is a patch-note event and an ADR if load-bearing. Format changes stay what ADR-0003 made them: ecosystem events with conformance vectors, never quiet.

Alternatives considered

  • Date-driven release trains (quarterly, etc.): rejected — the arc explicitly commits to order over schedule, and an empty train forces filler or slippage theater.
  • 1.0 at M4 unconditionally (format still v0): rejected — a stable release over an unstable wire format inverts the project's own data-outlives-software rule.
  • Major-version-per-★ (M8 = 2.0 regardless): rejected — SemVer digits that track marketing rather than compatibility train operators to ignore them.
  • Per-crate independent versioning: rejected for now — one workspace version keeps the compatibility matrix trivial while everything ships from one repo; revisit if crates gain independent consumers.

Graduation criteria

  • The version map above is reflected in the milestone tracking issues; the first tag (0.1.0 at M0) is cut by the 0005 pipeline end to end.
  • 1.0.0 ships with specs stamped v1 and the rc soak evidenced by linked conformance runs.
  • A dry-run security-patch release (tag → signed artifacts → notes) is exercised before 1.0.0 — the patch path is tested before it is needed.

Backward compatibility

  • Nothing exists to be compatible with yet; this proposal is the promise future releases are held to. It composes with proposal 0005 (integrity), ADR-0003 (format stamping), ADR-0022 (event-schema versioning), and ADR-0011 (schema-versioned records).

Open questions

  • Which platforms the static binary targets at 0.1.0 (linux x86_64/aarch64 certain; macOS for dev-eval likely; Windows undecided).
  • Whether the rc soak at M4 has a minimum-duration criterion or is purely gate-based (conformance green + no format defect + security review closed).
  • Container-image registry and naming (ghcr.io under the org, pending the ADR-0001 name check).