The rule as first written said release notes state what a reader gets and that withheld capabilities and failure modes belong in docs/architecture/. That is true but blunt enough to invite the wrong edit: applied mechanically it deletes a caveat a reader needs. Three cases, distinguished by whose experience the sentence describes. A capability that never existed leaves no expectation to correct, so a note about it reads as a feature. The implementation's journey is not the reader's experience either. A capability that shipped but is not yet wired is the reader's experience, and belongs as a caveat paired with the behaviour that compensates for it -- the release note is then the only place a reader learns they should not expect it to work yet. The last line says so outright, because the failure mode of this rule is someone applying it to a caveat. The gate ran and passed in the same conditional chain as this commit.
6.1 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 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.
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:latestand, 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 tomaindo 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-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.mdand the changelogs, and attaches the zip to the Release for the archied tag. The Release body is that version'sCHANGELOG.archied.mdsection. 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.