Releasing

Status: Accepted

How a release happens — the one page that answers “I want to cut a version, what do I do and what happens?” The version model lives in versioning; this is the process.

Satisfies: roadmap M10, E1, E2.

---

Each repo releases on its own clock

The implementation repos are the independent release streams — that’s the point of the decoupling. (Distinct from the three version identifiers the binary and manifest carry — lemonfiber, stack_version, schema_version — defined in versioning; a “stream” is a repo that tags, a “version” is a number it carries.)

A brand recolour does not force a binary release; a stack service bump does not force one either — the binary picks up a new embedded stack only when it is released with the submodule re-pinned.

Cutting a lemonfiber release

The binary is the one with real release engineering. The flow is tag-triggered — everything downstream is automatic:

flowchart TD
    tag["git tag v0.4.0 && push"] --> plan[cargo-dist plan]
    plan --> build[Build matrix:<br/>macOS arm64+x86 · Linux gnu+musl · Windows]
    build --> smoke[Smoke test: run the binary on each OS]
    smoke --> art[Signed artifacts + checksums]
    art --> rel["Draft release: installers, artifacts, attestations"]
    art --> tap[Regenerate homebrew-tap formula → PR/push]
    art --> inst[Shell + PowerShell installers]
    rel --> log[git-cliff: changelog from commits]
    log --> body["Release body: the changelog, then the installers"]
    body --> pub["A maintainer publishes"]
    pub --> docs[Docs site rebuilds on main]

Concretely, a maintainer does three things; CI does the rest:

1. Merge the version bump. The workspace’s Cargo.toml must already declare the version being released, on main, before anything is tagged — cargo-dist releases the tag whose version the workspace carries, so a tag cut over a stale one names a version nothing will build. This is a step in its own right rather than a thing to remember while doing the next one, because it is the one part of the sequence whose order matters and whose failure is silent until the release job runs. execute-version refuses to tag a repo that declares anything else, so getting it wrong costs a re-run rather than a deleted tag.
2. Dispatch execute-version with the version, dry_run first. It checks the goal gate, the no-stub rule, cross-stream compatibility, release blockers and the declared version, then tags every repo the manifest names. A version left at releasable blocks the next one from being staged, so this is not optional bookkeeping.
3. Review the drafted GitHub Release, and the homebrew-tap PR once that publish job is on (L1-R3), then publish. Publishing fires release-finalize, which records what shipped, pins the stack commit the release embedded, and regenerates the public roadmap.

Everything between step 2 and step 3 is cargo-dist and git-cliff. A draft is published by a person on purpose: it is the one step that reaches the outside world, and it is the last place to notice that what was built is not what was meant.

The version-bump decision

What moves, and when:

The one that needs coordination is schema_version: bumping it means the next lemonfiber release must support it, and build.rs will fail the build until the embedded stack and the binary agree (ARCH-R6). That failure is the safety net — an incompatible pairing cannot ship.

Every release is verifiable

Artifacts don’t just carry checksums — they carry provenance:

Both are carried today: cargo-dist emits the attestation via GitHub’s artifact attestations, so a consumer can verify a downloaded binary came from the real pipeline. It also raises the OpenSSF Scorecard signal the project already publishes.

OPS-R20 also obliges an SBOM (software bill of materials) per release, and that half is not produced yet — answering “are we affected?” still means reading Cargo.lock at the tag rather than a manifest of what went in.

The changelog is generated, not written

Commits follow a conventional-commit shape and carry Spec: trailers, so git-cliff produces the changelog from history. Nobody maintains CHANGELOG.md by hand — which also means a commit message is the release note, so write it for a reader.

It is generated after the build, onto the draft the pipeline leaves, because the pipeline is generated code: cargo-dist owns release.yml and rewrites it whole, so the changelog cannot live inside it. The release body ends up as the changelog first and cargo-dist’s install instructions second — the install half is the same every time, and the announcement that fires on publish is the body, so what changed is what a reader meets first.

Pre-1.0 versioning

Until 1.0.0, the binary is 0.y.z: y moves for features, z for fixes, and breaking changes are allowed within 0.x as the roadmap milestones land. 1.0.0 is cut when the M10 exit criteria are met — a non-contributor can install and run on all three platforms from the README alone.

The companion’s identities

The core trusts a device key only from an app it names (C10-R29). Its list of the official companion’s identities is empty until the companion’s first store release, so until then a stack trusts only the builds its operator adds to LEMONFIBER_DEVICE_KEY_APPS. The first store release adds a step to the core release that follows it:

1. Read the identities the stores sign the companion under. On Android the package and the SHA-256 of the app signing certificate Google Play signs with, not the upload key’s; on iOS the Team ID and the bundle ID.
2. Write them into the core’s official list in a pull request of their own, before the release is tagged.
3. Register a device key from the store build against a stack running that release, once on each platform, before the release is published.

A store build the shipped list does not name cannot register a device key on any stack that has not added it by hand, so this step is part of the release rather than a later fix.

The attestation status list

The core refuses an Android device key whose attestation chain Google lists as revoked or suspended, against a snapshot of Google’s attestation status list the build carries, since it fetches nothing at run time (C10-R34). Each core release takes a fresh snapshot:

1. Refresh the snapshot with the core repository’s refresh script, which reads the list from Google, checks its shape, and writes it into the tree with where it was read from and when.
2. Land it in a pull request of its own before the release is tagged, so the snapshot a release carries is one a reviewer saw.
3. Read its date back from lemonfiber version on the release build.

A snapshot only ages: a build released months ago still refuses what was revoked before it was cut and nothing since, which is why the version says when it was taken.

What a release must not do

The one-time setup

Releasing needs two things configured once (they can’t be scaffolded):

Both are documented as manual steps (Q-R60), like SONAR_TOKEN.

Requirements

A plugin is still gated by the train even though it is not cut by it: every run that would tag proves each registered plugin riding the version with the candidate build of the core commit it tags, through the reader the registry pins, and refuses on one that no longer validates (staging.md). Being an input to the gate and being a stream the gate tags are different things, and OPS-R59 is about the second.

A plugin builds an image where one of its services runs an image under ghcr.io/lemonfiber/ (bundle). Only such a plugin is a stream the train tags; one whose image is the upstream’s is pinned by revision and tree digest, with no release, because a tag adds nothing to a commit pin that is already content-addressed (OPS-R86).

A first-party plugin written against what the core had on main before any release carried it names that commit in its targets.toml rather than a release (F10). The bundle may pin it there, whether or not the pin names a release, because the release that embeds the bundle is cut from the same main: before the core is tagged, the train reads targets.toml at each pinned revision and refuses a pin whose commit the core commit being tagged does not hold, so everything the plugin was proved against is inside that release (OPS-R89). Once the release is published, the plugin names it instead of the commit.

Each image a first-party plugin builds is published from every commit on its main as well as from a train tag (OPS-R90), lemonfiber-decline’s and lemonfiber-request-gate’s included. It is built the way a tag builds it and tagged main- and the commit’s first twelve characters, and the publish moves the manifest’s pin to it through one rolling pull request (OPS-R91), so the manifest pins a real build before any release carries it. That pull request carries every recording the manifest names taken again from the new image, and the proofs.json written from them, so the plugin’s own check judges the pin it proposes (ADR-0049). A commit that changes nothing but a pin, its recordings, its proofs and its targets.toml publishes no image, so merging the pull request does not open the next. A commit image is not a release: nothing announces it, and merging its pin never moves the bundle. A train tag publishes the versioned image and its pin is the one the bundle follows.

Related

• staging.md — the spec-led, cross-repo release train this cut sits inside
• versioning — the version model this process applies
• ci-cd.md — the pipeline stages
• tooling.md — cargo-dist, git-cliff
• 30-repos/homebrew-tap.md — the generated formula
• roadmap M10