Files
archie/RELEASING.md
T
sam 9d8f364af1
Quality / check (push) Successful in 5m53s
deploy / gate (push) Canceled after 0s
deploy / archied-image (push) Canceled after 0s
deploy / agent-image (push) Canceled after 0s
deploy / dist-zip (push) Canceled after 0s
feat(releaseupdate): signed OCI distribution sources for releases and the catalogue (#1715)
2026-10-31 18:18:43 +11:00

7.0 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 five processes (archied, archie-gateway, archie-state-store, archie-ui, archie-messaging), 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 are not release 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 --atomic origin main v1.3.0  # both refs or neither

Pushing the tag is the release. The deploy workflow builds the images and the zip, then archied release publish signs the release with the RELEASE_SIGNING_KEY Actions secret and pushes it to git.catlow.cloud/sam/archie as v1.3.0, next, and stable unless the version is a prerelease. install.sh and the updater install only what that key signed.

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, which is why the push names the tag and is --atomic.

After a release, main and the working branch have diverged

The release commit lands on main — tools/release.sh refuses to run anywhere else — while the working branch keeps advancing. So after every release, main is ahead by exactly that commit and the branch is ahead by however far it has moved: neither tip is an ancestor of the other, and --ff-only fails in both directions. That refusal reads as "the tree is not ready" when in fact the tree is fine.

Merge the release commit into the branch first, so any conflict is resolved on the branch, where it is reversible and nobody is reading the tip:

git merge main                  # on the branch
git merge --ff-only <branch>    # then, in whichever worktree holds main

Confirm which worktree holds main with git worktree list before the --ff-only. A detached worktree sitting at the same commit will accept it and move nothing, which looks like success.

What a release publishes

Tagging one version produces, from a single deploy run:

  • Container images — git.catlow.cloud/sam/archied:latest and, on a release tag, git.catlow.cloud/sam/archie-agent:latest. The runtime image is rebuilt by the release, so runtime commits merged to main do not reach a running sandbox until the host pulls the new image. The hand-run tools/publish.sh publishes the same two images to git.catlow.cloud/sam instead, which is the registry the binary's default [containers].image names.
  • :latest names the newest release, not the newest commit. A push to main that is not a release publishes archied:edge (mutable, tracking main) and archied:sha-<commit> (immutable) instead, so a release's :latest stamping is not overwritten minutes later by the next ordinary commit. A host that runs releases follows :latest; a host that tracks main follows :edge.
  • A GitHub Release with a distribution zip — dist-zip builds every process the reference deployment runs (archied, archie-gateway, archie-state-store, archie-ui, archie-messaging) for linux/amd64, packs them with deployments/INSTRUCTIONS.md and CHANGELOG.md, and attaches the zip to the Release. The Release body is that version's ## [version] section of CHANGELOG.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 TEST_FLAGS=-count=1 before building images, then verifies any release tag at HEAD has a matching [version] section in CHANGELOG.md. The gate has one definition, in the Taskfile: the release runs it with the uncached suite, including the Docker-backed tests -short skips. 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.