DocsOpen app

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 version prints it), the container image tag, and the Helm chart (deploy/helm/zuppo/Chart.yaml: version and appVersion both 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 in crates/zuppo/schema/team-<format>.txt) and the solo state format (STATE_FORMAT) stay as the X.Y.0 release 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 N to N+2, run the last release of N+1 first.

Branches and tags

NameMeaning
maindevelopment; the next minor
vX.Y.0the minor release, on main
lts/X.Ythe long-term-support branch, cut from the tag vX.Y.0
vX.Y.Z-rc.Nrelease candidate N of X.Y.Z (on lts/X.Y for Z >= 1, on main for Z = 0)
vX.Y.Zthe 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:

FindingMeaning
schema-filea file under crates/zuppo/schema/ was added, changed or removed
format-const / format-tableTEAM_FORMAT, STATE_FORMAT or a FORMATS table (crates/zuppo/src/{team,solo}.rs) differs
ddlan 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-filea file was added or removed under a migrations/ directory
versionon 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

sh
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.lock entry) to the candidate version, builds the web UI, then cargo build --profile release-selfhost --locked -p zuppo.
  • Writes OUT/zuppo, OUT/SHA256SUMS and OUT/manifest.json (version, commit, ref, build time, host, rustc, profile, state format, team schema format and digest, binary digest and size, chart versions). Default OUT: /Users/lambiengcode/Documents/takumi/data/zf-host5/rc/<version>.

Nothing is uploaded or tagged.

Soak

sh
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-every s (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-every s (60): RSS, open file descriptors, state size, the schema fingerprint (team: the SCHEMA query of crates/zuppo/tests/team.rs, which equals crates/zuppo/schema/team-<format>.txt byte for byte; solo: .schema of every SQLite file under the state plus the format of zuppo-state.json), the heartbeat, a disk check;
  • every --restart-every s (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.sh clean on the candidate (base vX.Y.0), scripts/check.sh green.
  • 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.md verdict PASS. 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.Z on the soaked commit with the crate and chart versions set to the final X.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.