Two beads, one root: four sites stamped a version and only two of them were CI. `Taskfile.yml`'s build and `install.sh` derived GATEWAY_VERSION/RUNTIME_VERSION from `git describe`, so a from-source build claimed a release it was not running, and the stamp became a function of the commit graph -- the one input a content-checksum build cache cannot see. An empty commit moved `git describe` while `task build` reported "up to date" and shipped the previous stamp (archie-core-pdq2). Both sites now stamp `dev`: a source build says so, and the version a release carries is written into the artifact CI publishes. That removes the non-file input rather than caching it, and traceability for a local build is the checkout it came from. `deploy.yml` published `:latest` from any push to main, so a release's own stamping survived only until the next ordinary commit -- minutes, in an active repo -- and a host deploying :latest reported dev, leaving the update path unable to tell current from stale (archie-core-i5nb). `:latest` now moves only from a commit that IS a release; every other build publishes `:edge` (mutable, newest main) and `sha-<commit>` (immutable). A host that runs releases follows `:latest`; a host that tracks main follows `:edge`, which RELEASING.md now says. Verified: `task build` reports `archied dev`; the new workflow test fails against the old workflow on all five guards and passes after; deploy.yml parses; install.sh passes `bash -n`. Gated with `task check` (exit 0) at8faa0f6a-- the v1.39.0 base, CI-green -- with these five files applied. It is NOT gated at HEAD: HEAD carries an unrelated red, `TestTaskProtoCarriesEveryDomainField`, becaused6f61c2cadded ParkClass and RemediationRounds without the proto mapping. This change neither causes nor fixes that.
5.5 KiB
Releasing
One release stream. CHANGELOG.md carries every release section, one generated page
per version describes it, and one tag names the release. A release is one version
covering whatever changed; the components' entries are labelled sections inside it
(### archied, ### archie-agent), not separate numbers or separate pages.
The host bundle ships six processes — archied, archie-gateway,
archie-state-store, archie-ui, archie-messaging, archie-playbooks — and one
version covers all of them. archie-agent, the per-task sandboxed runtime, ships as a
container image and its changes are the ## [version] release's ### archie-agent
section.
tools/release.sh decides which commits a release carries from the package closure of
every shipped binary, not from commit-message guessing: a change to a package only
the messaging service, state store, playbook runner or UI links still lands in the
changelog. Read its header comment for how it partitions commits and enforces
main-only, clean-tree releases.
What justifies a version
task release:preview VERSION=X.Y.Z shows exactly what would land, before anything is
written. A commit set that justifies no version produces no version: release.sh
exits 3 with "nothing to release" rather than inventing one, so a pipeline can
finish green without tagging.
Most sessions touch the gateway side (daemon, gateway, web UI, chat, messaging) and
leave the agent runtime alone. That is no longer a per-component skip decision — one
version covers the release — but a runtime code change being merged to main is still
not the same as it being in production: the archie-agent image is rebuilt by the
release, and a host that runs the agent must pull the new image
(docker compose pull agent) to get it.
What the notes are for
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 — is not the reader's experience either — out.
- A capability that shipped but is not 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 belong in docs/architecture/,
where implementers look, because there they are requirements rather than news.
Do not apply this mechanically: deleting a caveat a reader needs misleads them,
which is the failure this rule exists to prevent.
Cutting a release
task release:preview VERSION=1.3.0 # preview what would land
task release:prepare VERSION=1.3.0 # write the section into CHANGELOG.md, uncommitted
# edit CHANGELOG.md -- generated notes are a starting point, not the release
task release VERSION=1.3.0 # commit + annotated tag
git push origin main --follow-tags # CI stamps images with real versions
release:prepare emits bare commit subjects; they are a starting point. Rewrite them
to say what a reader gets, per "What the notes are for" above.
Pushing is a separate, explicit step — never push without confirming first (see the
repo's general "check before doing anything hard to reverse" rule). The deploy
workflow reads tags pointing at HEAD; pushing the commit without its tag gets images
stamped dev.
What a release publishes
Tagging one version produces, from a single deploy run:
- Container images —
ghcr.io/samcharles93/archied:latestandghcr.io/samcharles93/archie-agent:latest. The runtime image is rebuilt by the release, so runtime commits merged tomaindo not reach a running sandbox until the host pulls the new image. :latestnames the newest release, not the newest commit. A push tomainthat is not a release publishesarchied:edge(mutable, trackingmain) andarchied:sha-<commit>(immutable) instead, so a release's:lateststamping is not overwritten minutes later by the next ordinary commit. A host that runs releases follows:latest; a host that tracksmainfollows:edge.- A GitHub Release with a distribution zip —
dist-zipbuilds every process the reference deployment runs (archied,archie-gateway,archie-state-store,archie-ui,archie-messaging,archie-playbooks) for linux/amd64, packs them withdeployments/INSTRUCTIONS.mdandCHANGELOG.md, and attaches the zip to the Release. The Release body is that version's## [version]section ofCHANGELOG.md.
The zip is also uploaded as an Actions artifact, but that is a backup copy: artifacts expire after 90 days and need an Actions login to download. The Release asset is the durable, operator-reachable one.
Gate
CI (deploy.yml) runs task check before building images, then verifies any release
tag at HEAD has a matching [version] section in CHANGELOG.md. A tag with no
changelog entry is a hard failure. No tags at HEAD is a warning, not a failure —
images get stamped dev.
One consequence worth knowing when a release commit needs amending: GitHub Actions
runs the workflow from the commit that triggered it, so a fix to deploy.yml only
takes effect for a release if it is an ancestor of the tagged commit. Delete and re-cut
the tag (git tag -d, task release) rather than committing the fix on top of an
already-tagged release.