Files
archie/RELEASING.md
T
sam 9ad239b36e fix(releaseupdate): find releases in the public releases repository
The source repository is private, so the updater and install.sh got 404.
Releases are now published to samcharles93/archie-releases by
task release:publish.
2026-10-16 03:11:14 +11:00

137 lines
6.7 KiB
Markdown

# 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
```bash
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
task release:publish VERSION=1.3.0 # images to GHCR, zip to archie-releases
```
The source repository is private, so releases are published to the public
`samcharles93/archie-releases` repository, where `install.sh` and the
updater find them. `release:publish` builds from a clean worktree of the tag
and needs `gh` and `docker` logged in with write access to that repository
and to GHCR.
`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:
```bash
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** — `ghcr.io/samcharles93/archied:latest` and
`ghcr.io/samcharles93/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.
- **`: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` before building images, then verifies any
release tag at `HEAD` has a matching `[version]` section in `CHANGELOG.md`. 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.