Bead archie-core-8cda.5.5: - task dev now runs archie-ui (dev:dashboard) on :8484 -- after the cutover archied binds no dashboard listener, and Vite's /api,/events proxy needs a live receiver there. dev:mobile starts archie-ui with a LAN bind and -token-file (reusing the pre-cutover token path) instead of a mobile archied overlay; dev:ui's summary points at archie-ui. - deployments/dev.toml documents itself as the archie-ui overlay and states the [services.gateway] target explicitly. - systemd-user-service.md: the auth gap is now the documented posture -- archie-ui has no secret registry, resolves GATEWAY_TOKEN/ STATE_STORE_TOKEN from its process environment only, so the starter (EnvironmentFile) exports them; worked env-file example added, plus /healthz as the token-free liveness probe. - INSTRUCTIONS.md ships five binaries with archie-ui in the quickstart and the token story; README.md carries the auth note; the docker-nats-stack profile notes archie-ui binds [web] and dials the same [services.*] targets. - release tooling: archied's component closure extends with cmd/archie-ui and internal/app/archieui, so a UI-process-only commit can no longer fall between the two changelogs; RELEASING.md documents that the UI Service ships inside the archied release.
72 lines
3.6 KiB
Markdown
72 lines
3.6 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`.
|
|
|
|
## 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`.
|