Releases and the LTS line (HOST-5)
The policy is plan DEP-9 (the upgrade policy), DEP-7 (the two profiles) and DEP-10 (the parity rule).
The policy is plan DEP-9 (the upgrade policy), DEP-7 (the two profiles) and DEP-10 (the parity rule). This file is what a release manager follows; scripts/lts-*.sh are the parts a machine can check.
Versions
- Semver, one version for everything that ships: the crate
crates/zuppo(zuppo versionprints it), the container image tag, and the Helm chart (deploy/helm/zuppo/Chart.yaml:versionandappVersionboth equal the crate version, pre-release suffix included). - Monthly minors (
0.2.0,0.3.0, ...) carry features and, when needed, schema changes. - Patch releases (
X.Y.Z,Z >= 1) are security and bug fixes. They never carry a schema change: the team schema format (TEAM_FORMAT, pinned incrates/zuppo/schema/team-<format>.txt) and the solo state format (STATE_FORMAT) stay as theX.Y.0release had them, so a patch upgrade is a binary or container replacement and nothing else. - Migrations are forward only (expand, then contract in a later minor). A start on state written by a newer zuppo or a newer format is refused (
downgrade refused); rollback is a backup restore, not a downgrade. - Straight upgrade to the latest release within a major, with one stop per major: to cross from major
NtoN+2, run the last release ofN+1first.
Branches and tags
| Name | Meaning |
|---|---|
main | development; the next minor |
vX.Y.0 | the minor release, on main |
lts/X.Y | the long-term-support branch, cut from the tag vX.Y.0 |
vX.Y.Z-rc.N | release candidate N of X.Y.Z (on lts/X.Y for Z >= 1, on main for Z = 0) |
vX.Y.Z | the release |
One minor a year becomes an LTS. lts/X.Y gets security fixes only for about 15 months: backports of fixes already on main, nothing else: no features, no schema change. When the window closes the branch is archived and its last tag stays.
The guard
scripts/lts-guard.sh [--base REF] [--head REF] compares HEAD with the base (on lts/X.Y, the tag vX.Y.0; a missing tag is an error) and fails with one line per finding:
| Finding | Meaning |
|---|---|
schema-file | a file under crates/zuppo/schema/ was added, changed or removed |
format-const / format-table | TEAM_FORMAT, STATE_FORMAT or a FORMATS table (crates/zuppo/src/{team,solo}.rs) differs |
ddl | an added or removed line of a .rs or .sql file under crates/ or enterprise/ matches CREATE/ALTER/DROP ... TABLE/INDEX/POLICY/TRIGGER/VIEW/TYPE/SCHEMA/EXTENSION, ADD COLUMN, DROP COLUMN, RENAME TO/COLUMN (case-insensitive) |
migration-file | a file was added or removed under a migrations/ directory |
version | on lts/X.Y only: the crate version is not X.Y.Z with Z >= 1 (a pre-release suffix is fine; a tree equal to the base's needs no bump), the patch is below the base's, or Chart.yaml (when present) has a version or appVersion that differs from the crate's |
The ddl check is textual and strict on purpose: a DDL-looking line in a comment or a string fails too. A false positive is cleared by rewording the line, never by an exemption list. The guard compares committed trees, not the working copy. Exit 0 clean, 1 findings, 2 usage or a ref that does not resolve. scripts/lts-check.sh tests it on a synthetic repository (a case per finding) and scripts/lts-rc.sh runs it first.
Release candidate
scripts/lts-rc.sh --version X.Y.Z-rc.N [--ref lts/X.Y]
- Runs the guard (only when the ref is on a branch
lts/X.Y; otherwise it says so and skips). - Exports the tracked files of the ref into a scratch directory, sets the crate version (and its
Cargo.lockentry) to the candidate version, builds the web UI, thencargo build --profile release-selfhost --locked -p zuppo. - Writes
OUT/zuppo,OUT/SHA256SUMSandOUT/manifest.json(version, commit, ref, build time, host, rustc, profile, state format, team schema format and digest, binary digest and size, chart versions). DefaultOUT:/Users/lambiengcode/Documents/takumi/data/zf-host5/rc/<version>.
Nothing is uploaded or tagged.
Soak
scripts/lts-soak.sh start --rc OUT [--out SOAK] [--days 7] [--profiles solo,team] scripts/lts-soak.sh status --out SOAK # alive or dead, heartbeat age, verdict when finished scripts/lts-soak.sh wait --out SOAK # until the driver exits; prints result.md scripts/lts-soak.sh stop --out SOAK # kills only the recorded driver
start refuses below 30 GiB free disk, copies the RC binary and the pinned git to SOAK/bin (checking SHA256SUMS), and starts the driver detached (on macOS under caffeinate -i, so the host does not idle-sleep during the soak); it prints the planned end and returns. The driver runs zuppo serve for each profile: solo on a state directory on local disk, team against a throwaway Postgres and MinIO in Docker (containers zuppo-soak-<pid>-pg and -s3). It bootstraps an org, two people, grants and a repository through zuppo admin apply, then:
- every
--workload-everys (15): a push of a new commit and a fetch verification over HTTP (and over SSH when the host has a client),/healthz,zuppo admin status; - every
--sample-everys (60): RSS, open file descriptors, state size, the schema fingerprint (team: theSCHEMAquery ofcrates/zuppo/tests/team.rs, which equalscrates/zuppo/schema/team-<format>.txtbyte for byte; solo:.schemaof every SQLite file under the state plus theformatofzuppo-state.json), the heartbeat, a disk check; - every
--restart-everys (21600): SIGTERM and restart on the same state and binary, then the fingerprint must be unchanged and earlier pushes still served.
The first fingerprint after the bootstrap is the baseline; any later difference is a `schema_changed` event and fails the soak, as does a crash (the process is restarted once, event crash), a failed workload operation, a format number that differs from the RC's manifest, a run shorter than requested, or a solo idle RSS median above 150 MiB (PC27). Losing the infrastructure (Docker gone, containers gone) or dropping below 20 GiB free disk gives verdict INVALID, which is neither a pass nor a schema failure: rerun it. Output under SOAK: samples.jsonl, events.jsonl, driver.log, heartbeat, and at the end result.json and result.md.
Acceptance: an RC soaks 7 days with no schema change (verdict PASS).
From RC to release
lts-guard.shclean on the candidate (basevX.Y.0),scripts/check.shgreen.lts-rc.sh --version X.Y.Z-rc.N; keep its output directory with the manifest.lts-soak.sh start --rc ...for 7 days;result.mdverdictPASS. Any change to the tree (a fix) is a new RC and a new soak.- Parity (DEP-10), by hand: the code ran at least 2 weeks in cloud production on both targets, and the conformance suite is green on it.
- Tag
vX.Y.Zon the soaked commit with the crate and chart versions set to the finalX.Y.Z(the soaked binary differs from the release only in the version string). - Publish (see below), then announce.
Not done by these scripts
Publishing is a human or CI step, later: crates.io, container images and their signatures, cargo-dist archives, the Helm chart repository, Homebrew, the NixOS module, release notes and security advisories. The scripts build, check and soak locally; they push, tag and upload nothing.