130 lines
6.4 KiB
Markdown
130 lines
6.4 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 six processes — `archied`, `archie-gateway`,
|
|
`archie-state-store`, `archie-ui`, `archie-messaging`, `archie-playbooks` — 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 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.
|
|
|
|
## 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 origin main --follow-tags # CI stamps images with real versions
|
|
```
|
|
|
|
`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`.
|
|
|
|
### 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`, `archie-playbooks`) 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.
|