Files
archie/RELEASING.md
T
sam 0e931485a0
Quality / check (push) Successful in 7m33s
deploy / gate (push) Successful in 6m27s
deploy / archied-image (push) Successful in 2m57s
deploy / agent-image (push) Successful in 12s
deploy / dist-zip (push) Skipped
docs(releaseupdate): use contractions in the release and canary text (#1716)
2026-10-31 22:18:57 +11:00

6.7 KiB
Raw Permalink Blame History

Releasing

One release stream. CHANGELOG.md carries every release section, one generated page per version describes it, and one v* tag names the release. One version covers every process in the host bundle (archied, archie-gateway, archie-state-store, archie-ui, archie-messaging) and the archie-agent image; per-component detail is a labelled section inside the version (### archied, ### archie-agent).

A release is cut by CI, published to next, run on the canary for a day, and promoted to stable only if the canary's signals pass. Nothing is run locally.

Notes are written with the change

A commit that changes what a reader experiences adds its bullet under ## [Unreleased] in CHANGELOG.md, in the same commit. The release takes that section as it stands, so write the bullet as the release note, not as a commit subject.

Release notes describe the reader's experience of what shipped. The test is the reader, not whether a sentence is negative:

  • A capability that never existed leaves no expectation to correct, so a note about it reads as a feature to someone who never had the thing: out.
  • The implementation's journey (what was rebuilt, what a guard finally covers, what a browser API refuses to surface) isn't the reader's experience either: out.
  • A capability that shipped but isn't yet wired is the reader's experience, so it belongs, worded as a caveat on the capability and paired with the behaviour that compensates for it.

Design constraints and withheld capabilities are not release news. Deleting a caveat a reader needs misleads them, which is the failure this rule exists to prevent.

Cutting a release

Dispatch the release workflow (.github/workflows/release.yml) with major, minor, patch or an exact version. It runs task release on main:

  1. refuses a dirty tree, an existing tag, or an [Unreleased] with no entries;
  2. turns [Unreleased] into ## [x.y.z] - date under a new empty [Unreleased], and runs task news;
  3. commits chore(release): vx.y.z and tags vx.y.z;

then pushes main and the tag atomically with DEPLOY_TOKEN. A push made with the job token wouldn't start other workflows, so the user token is what lets the tag start the deploy.

After a release, pull main before committing on it again: CI has added the release commit.

What a release publishes

The tag push runs deploy.yml:

  • Gate. task check TEST_FLAGS=-count=1 (uncached, including the Docker-backed tests -short skips) and govulncheck, then a check that the tag has a [version] section in CHANGELOG.md.
  • Images. archied:v<version> and archie-agent:v<version> on a release tag; archied:edge and archied:sha-<commit> on any other push to main. :latest moves only on promotion, so it names the newest promoted release.
  • The signed release. archied release publish signs a statement (version, issued_at, zip digest, agent image by digest) with RELEASE_SIGNING_KEY and pushes it with the distribution zip to git.catlow.cloud/sam/archie as v<version> and next. It never moves stable.
  • The release-notes page on Gitea, from that version's CHANGELOG.md section, which the statement links to.
  • The canary install: archied release canary start points the canary at next and installs the release through its dashboard.

GitHub-style Actions run the workflow from the tagged commit, so a fix to deploy.yml reaches a release only if it is an ancestor of the tag. Re-cut the release rather than committing the fix on top of a tagged one.

The canary

The canary is the production host, following next. Every quarter hour canary.yml runs archied release canary check, which reads the canary through its dashboard API and judges the release on next:

Signal Source Fails when
Install outcome GET /api/chat/update the canary doesn't run the release (the watchdog rolled it back)
Readiness GET /health/detailed the rollup isn't ok
Alerts GET /api/alerts an open action alert was first raised after the release was issued
Error log GET /api/logs?level=error error lines per day exceed 2 × baseline + 10
Task outcomes GET /api/tasks the share of finished tasks that parked or died rose more than 10 points
  • Control. The canary's own 24 hours before the release was issued. With one production host there's no simultaneous control.
  • Window. 24 hours from issue, one cycle of schedules and traffic. The first 30 minutes are for the install and restart.
  • Hard signals (install, readiness, alerts) roll back at any check after that. Relative signals (errors, tasks) are judged at the end of the window.
  • Too little data skips a signal rather than failing it: fewer than 5 finished tasks in the window, or an error log that reaches back less than an hour into the baseline. A log read that stops short of a window is scaled to a full day from what it covers.

Promote

A release that passes the window is promoted: stable is retagged to the v<version> manifest. The signature covers the statement, not the tag, so the retag needs no signing key. The archied and archie-agent images' :latest move to their :v<version> first, and the agent image must be the digest the statement pins. Promotion refuses a prerelease and a release issued before the one stable names, the same replay rule hosts enforce. The decision and its reasons are in the canary run log.

Roll back

stable stays put, and the run turns red. The canary is pinned to the stable version through its update settings and reinstalled through its dashboard.

A release whose migrations differ from stable's can't go back without restoring the pre-update database snapshot, which loses every write since. The canary is held on the failed release instead (pinned to it) and the fix goes forward in the next release. The next release's deploy points the canary back at next.

A pinned canary isn't judged, so a rollback is decided once.

Configuration

Name Kind Holds
CANARY_URL Actions variable the canary's dashboard URL; unset disables the canary steps
CANARY_TOKEN Actions secret a personal API token on the canary with instance admin
DEPLOY_TOKEN Actions secret registry and repository write, for publishing, promoting and the release push
RELEASE_SIGNING_KEY Actions secret the release signing seed

The runner must reach CANARY_URL. Without a canary a release stays on next until promoted by hand, under the same refusals:

archied release promote -version 1.57.0 \
  -latest git.catlow.cloud/sam/archied,git.catlow.cloud/sam/archie-agent