6.7 KiB
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:
- refuses a dirty tree, an existing tag, or an
[Unreleased]with no entries; - turns
[Unreleased]into## [x.y.z] - dateunder a new empty[Unreleased], and runstask news; - commits
chore(release): vx.y.zand tagsvx.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-shortskips) andgovulncheck, then a check that the tag has a[version]section inCHANGELOG.md. - Images.
archied:v<version>andarchie-agent:v<version>on a release tag;archied:edgeandarchied:sha-<commit>on any other push tomain.:latestmoves only on promotion, so it names the newest promoted release. - The signed release.
archied release publishsigns a statement (version, issued_at, zip digest, agent image by digest) withRELEASE_SIGNING_KEYand pushes it with the distribution zip togit.catlow.cloud/sam/archieasv<version>andnext. It never movesstable. - The release-notes page on Gitea, from that version's
CHANGELOG.mdsection, which the statement links to. - The canary install:
archied release canary startpoints the canary atnextand 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