The v1.30.0 extraction moved Telegram, email and webhook out of archied and into cmd/archie-messaging, and nothing packaged it. dist-zip built and copied only the five older binaries, and scripts/archie-update-install omitted it from both its service and binary lists. A host upgraded across v1.30.0 therefore ran on with no messaging process at all: archied logged that it stopped serving the telegram gateway at the extraction, nothing replaced it, and the bot was dead for two days with no error anywhere -- the daemon looked healthy throughout (archie-core-1c01). Fixed in all four places the host component set was enumerated: the zip's build loop, the zip's copy list, the installer's GATEWAY_SERVICES (messaging is a service, so it is installed AND restarted) and its GATEWAY_BINARIES. The comment claiming every process in the documented deployment ships in the zip is now true, and says what makes it true. The duplication was the actual defect, so the sets are pinned to cmd/ instead: TestHostCommandListsCannotDrift derives the host-run commands from cmd/ and asserts all four lists, plus the reference runbook's units, agree with it. Adding a command or extracting one fails the test until it is packaged -- the check that would have caught this on the day. The installer's own test grew the same coverage, and the reason it passed while the bug was live is worth recording: its fixture created only the stale cmd/ set, so the script's `[ -d ./cmd/$cmd ]` guard silently skipped messaging. Documentation, because the installer now refuses an update when a service unit is missing and sends the operator to the runbook -- so a service the runbook omits is a dead end: a messaging unit in deployments/systemd-user-service.md, the component list and start sequence in deployments/INSTRUCTIONS.md (which ships inside the zip), and the packaged-binary list in RELEASING.md. Verified: task check exit 0, including test:tools and test:ui. Both new guards were made to fail on purpose: reintroducing each omission produces "missing archie-messaging" and "no call with fragments [./cmd/archie-messaging]".
101 lines
5.1 KiB
Markdown
101 lines
5.1 KiB
Markdown
# 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.
|
|
|
|
## Process
|
|
|
|
```bash
|
|
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.
|
|
|