Files
archie/RELEASING.md
T
sam c43bd46ecb docs(news): state what a reader gets, and move the design where it is read
The v1.36.0 release note carried four things a reader cannot use. The dashboard's
seven in-browser tools and the installtype fix stay; the withheld judgement verbs,
the consequentialHint limitation and the two silent-failure notes are removed from
the release feed and moved to where an implementer looks.

  - The four verbs are withheld because an agent that can approve can approve its
    own work. That is settled design, so it now sits in docs/architecture/identity.md,
    beside the approval-path conflict it belongs with, stated as the constraint it is:
    attribution, not capability, is what releasing them depends on.
  - The browser-tool surface had no home in docs/architecture, so it has one now:
    docs/architecture/dashboard-agent-tools.md holds what a tool call can be
    attributed to, why confirmation is a signal rather than a control, and the two
    ways the surface fails silently.

Audited 1.35.0, 1.36.0 and 1.37.0 for the same class. 1.37.0 is clean. 1.35.0 carried
two build notes: a bullet recounting that a guard had never been written because it
failed, and a clause about a manager "finally" having a production writer. Both are
gone; the capabilities they were attached to remain.

RELEASING.md now carries the rule so the next release reads it: release notes state
what a reader gets, and design constraints, withheld capabilities and failure modes
belong in docs/architecture/, because a note about an absence reads as a feature to
someone who never had the thing.

docs/news/** is regenerated by task news, never hand-edited. task check passed before
this commit: the chain runs it, so a failing gate commits nothing.
2026-09-22 16:53:27 +10:00

5.6 KiB

Releasing

Two components, independently versioned: archied (gateway/daemon) and archie-agent (runtime). Tags are archied/vX.Y.Z and archie/vX.Y.Z. CHANGELOG.md / CHANGELOG.archied.md / CHANGELOG.archie.md document the split — see those for what each component actually is.

The UI Service (archie-ui) is not a third component: it ships inside the archied release, versioned by the same archied/vX.Y.Z tag. It shares internal/webui (dashboard HTTP layer, embedded SPA) with the daemon, so the two move together; tools/release.sh extends archied's go list -deps closure with cmd/archie-ui and internal/app/archieui for exactly this reason — without them a commit touching only the UI process would land in neither changelog.

The standing rule

Only version a component that actually has unreleased commits touching its own package closure. tools/release.sh decides this mechanically (go list -deps, not commit-message guessing — see its header comment), and task release:preview VERSION=X.Y.Z shows you the split before anything is written. If a component's list comes back empty, or its only entries are unrelated backlog from before the change you're actually releasing, skip it: pass RUNTIME=skip or GATEWAY=skip. Do not bump a component's version just because the other one moved, and do not bundle a large unrelated backlog into a release "because it's due" — that's a separate release, on its own review pass, not a rider on this one.

In practice: most sessions touch archied (webui, gateway, daemon, chat, archieui) and leave archie-agent (the per-task sandboxed runtime) untouched, so most releases are gateway-only with RUNTIME=skip. Don't ask whether to skip an untouched component — skip it, and say so in the handoff. Only ask when the runtime genuinely has unreleased changes and there's a real judgment call about whether to bundle a large pre-existing backlog in or cut it separately.

Note that a runtime code change (e.g. something in internal/app/agentworker) being merged to main is not the same as it being in production — the archie-agent Docker image isn't rebuilt by a gateway-only release. If a change needs the new agent image to actually take effect, say so explicitly and either cut an agent release or note that docker compose build agent / docker compose pull agent is needed separately.

What the notes are for

Release notes state what a reader gets. A reader scanning releases does not need to know what was withheld, what a browser API cannot do, or what the engineering took; and a note about an absence reads as a feature to someone who never had the thing. Design constraints, withheld capabilities and failure modes belong in docs/architecture/, where implementers look, because there they are requirements rather than news.

task release:preview VERSION=1.3.0     # preview what would land, both components
task release:prepare VERSION=1.3.0     # write changelog sections, uncommitted
# edit CHANGELOG.archied.md and CHANGELOG.archie.md -- generated notes
# are a starting point, not the release
task release VERSION=1.3.0             # commit + tag
git push origin main --follow-tags     # CI stamps images with real versions

Pass GATEWAY=<ver> / RUNTIME=<ver> to version the two components independently, or skip on either to hold it back per the rule above. All three task release:* targets forward to tools/release.sh — read its header comment for exactly how it partitions commits and enforces main-only, clean-tree releases.

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 tags gets images stamped dev.

What a release publishes

Tagging both components at one commit produces, from a single deploy run:

  • Container images — ghcr.io/samcharles93/archied:latest and, when the runtime moved, ghcr.io/samcharles93/archie-agent:latest. A gateway-only release (RUNTIME=skip) does not rebuild the agent image, so runtime commits merged to main do not reach a running sandbox until an agent release is cut and the host pulls the new image.
  • 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, archie-playbooks) for linux/amd64, packs them with deployments/INSTRUCTIONS.md and the changelogs, and attaches the zip to the Release for the archied tag. The Release body is that version's CHANGELOG.archied.md section. Both jobs are keyed to the archied tag, so a gateway-only release still produces the zip.

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 its changelog. 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 tags (git tag -d, task release) rather than committing the fix on top of an already-tagged release.