docs(release): record the one-stream process, and stop process scopes inflating versions
RELEASING.md still described two independently versioned components, GATEWAY and RUNTIME release inputs, and a `task release:prepare` invocation that no longer exists. It is the file someone reads to cut a release, so a stale one is worse than none. The PRD's version computation carried a real flaw: a commit whose scope is the repository's own machinery could still bump the product's version, so the first improvement anyone made to the release process would inflate it -- which is exactly what `feat(release)` would have done to this cut. Non-product scopes (`release`, `ci`, `docs`, `build`, `test`) now contribute no bump.
This commit is contained in:
1 parent
46e9618bd2
commit
3a15136566
3 files changed
+64
-77
No files matched your search
+58
-76
@@ -1,45 +1,35 @@
|
||||
# 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.
|
||||
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 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 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.
|
||||
|
||||
## The standing rule
|
||||
`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.
|
||||
|
||||
**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.
|
||||
## What justifies a version
|
||||
|
||||
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.
|
||||
`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.
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
@@ -60,59 +50,51 @@ 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, 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
|
||||
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
|
||||
```
|
||||
|
||||
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.
|
||||
`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 tags gets images stamped `dev`.
|
||||
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`.
|
||||
|
||||
## What a release publishes
|
||||
|
||||
Tagging both components at one commit produces, from a single `deploy` run:
|
||||
Tagging one version 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.
|
||||
- **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.
|
||||
- **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.
|
||||
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.
|
||||
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.
|
||||
@@ -340,7 +340,7 @@
|
||||
"url": "/dev/prds/release-stream-and-commit-rules/",
|
||||
"title": "One release stream, one page per version, and commit rules — decision",
|
||||
"section": "PRDs",
|
||||
"body": "# One release stream, one page per version, and commit rules — decision\n\n**Status:** Draft\n**Date:** 2026-09-22\n**Authority:** `RELEASING.md` for the process this changes, `AGENTS.md` for the\ncommit rules it enforces, and `tools/newsgen` for the artifact shape.\n\n**Supersedes:** `docs/prds/news-and-releases.md`, sections \"Source of truth\" and\n\"Two components\" — one changelog replaces two, and one page per version replaces\none page per component. Its remaining decisions stand.\n\n## Decision\n\n**A release is one version covering whatever changed.** One changelog holds every\nrelease section, one generated page holds every version's notes, and an operator\ncutting a release names one version.\n\n## One changelog\n\nEvery release section lives in `CHANGELOG.md`, newest first. `CHANGELOG.archied.md`\nand `CHANGELOG.archie.md` are deleted, and `CHANGELOG.md` stops being a pointer to\nthem. The changelog is the only source of release prose, and tags are not a source:\nCI and deployment check out shallow, so tags are absent from a site build while the\nchangelog is always present.\n\n### The merged history\n\nTwo version streams become one file, so a version that both components released\ncarries one heading and one date: **the newest date among that version's sections**,\nbecause a version's date is when the last part of it shipped. Where a component's own\ndate differs from it, that component's section label carries its own date, so the\nper-component fact survives the merge rather than being collapsed into the heading.\n\nThe merged history holds 65 versions: 33 that both components released, 31 only\n`archied`, and one only `archie`, from 64 and 34 sections respectively, so 98\npublished pages become 65. `## [Unreleased]` is not a release -- it carries no\nversion and gets no page -- but it stays at the top of the file, because it is\nthe one place unfinished work is recorded. Counting `##` headings rather than\nreleases overcounts by one.\n\nThis ambiguity is historical only. One version stream with one tag gives a version\nexactly one date, so the rule represents the merged past rather than a design that has\nto hold.\n\nThe merge is verified by content, not by the generator succeeding: the section count\nper source, the merged version set equal to the union of both sources with nothing\nextra, and every section title still present. A generator that agrees with the file it\njust wrote is evidence of nothing.\n\n## One version stream\n\n**`GATEWAY` and `RUNTIME` stop being release inputs.** `release:prepare` and\n`release:tag` take one version, and `tools/release.sh` loses the two flags.\n\nThey may stay as build-time stamps, because a binary must still report what it\ncontains. A release that must name three versions forces an operator to pass skip\nvalues for components that did not change, and that ceremony is what this decision\nremoves — along with the drift it allows, where two components' tags fall a release\napart.\n\n**Per-component detail stays, as sections inside the release.** A reader still needs\nto know whether `archied` or the agent changed; what goes away is the separate\nnumbers and the separate pages, not the information.\n\n**History is not re-tagged.** Existing tags keep their names, because tags are not a\nsource and nothing reads them to build a page. A future reader must not \"fix\" the\nunified changelog by rewriting tags to match it.\n\n## One release page per version\n\n`docs/news/\u003cversion\u003e.md` replaces `docs/news/\u003ccomponent\u003e/\u003cversion\u003e.md`, carrying the\nrelease's per-component sections inside it.\n\n**Every release URL already published keeps working.** `/news/archied/\u003cversion\u003e` and\n`/news/archie/\u003cversion\u003e` route to the unified page for that version. The generator\nemits the redirect table beside the pages so it cannot drift from them; if the\nrenderer needs the table in its own repository, that is a change in that repository\nrather than a hand-maintained list here.\n\n## The reviewer runs between prepare and tag\n\nRelease notes are prose, and the review agent exists to review prose. **`release:tag`\nrefuses to tag when the review has not been run for that version, or when it reports\nat the level.**\n\nThe invocation is verified rather than assumed. `tl rules --lint` reports `corpus ok`\nand exits 0. `tl review \u003cpath\u003e --deadline \u003cms\u003e --max-turns \u003cn\u003e` reports\n`0 findings (0 high, 0 medium) · 1/1 files reviewed · clean` and exits 0 on\n`docs/news/archied/1.36.0.md`.\n\n**`--fail-on` must be passed explicitly.** It defaults to `never`, so an invocation\nwithout it cannot refuse anything and the step would be decorative. `--fail-on high`\nis the level: a medium finding in a release note is worth acting on, and it should not\nstop a release on its own.\n\n**The rule is stated once.** It belongs in the reviewer's own rule set, which\n`tl rules --from-doc` can draft frLine truncated
|
||||
"body": "# One release stream, one page per version, and commit rules — decision\n\n**Status:** Draft\n**Date:** 2026-09-22\n**Authority:** `RELEASING.md` for the process this changes, `AGENTS.md` for the\ncommit rules it enforces, and `tools/newsgen` for the artifact shape.\n\n**Supersedes:** `docs/prds/news-and-releases.md`, sections \"Source of truth\" and\n\"Two components\" — one changelog replaces two, and one page per version replaces\none page per component. Its remaining decisions stand.\n\n## Decision\n\n**A release is one version covering whatever changed.** One changelog holds every\nrelease section, one generated page holds every version's notes, and an operator\ncutting a release names one version.\n\n## One changelog\n\nEvery release section lives in `CHANGELOG.md`, newest first. `CHANGELOG.archied.md`\nand `CHANGELOG.archie.md` are deleted, and `CHANGELOG.md` stops being a pointer to\nthem. The changelog is the only source of release prose, and tags are not a source:\nCI and deployment check out shallow, so tags are absent from a site build while the\nchangelog is always present.\n\n### The merged history\n\nTwo version streams become one file, so a version that both components released\ncarries one heading and one date: **the newest date among that version's sections**,\nbecause a version's date is when the last part of it shipped. Where a component's own\ndate differs from it, that component's section label carries its own date, so the\nper-component fact survives the merge rather than being collapsed into the heading.\n\nThe merged history holds 65 versions: 33 that both components released, 31 only\n`archied`, and one only `archie`, from 64 and 34 sections respectively, so 98\npublished pages become 65. `## [Unreleased]` is not a release -- it carries no\nversion and gets no page -- but it stays at the top of the file, because it is\nthe one place unfinished work is recorded. Counting `##` headings rather than\nreleases overcounts by one.\n\nThis ambiguity is historical only. One version stream with one tag gives a version\nexactly one date, so the rule represents the merged past rather than a design that has\nto hold.\n\nThe merge is verified by content, not by the generator succeeding: the section count\nper source, the merged version set equal to the union of both sources with nothing\nextra, and every section title still present. A generator that agrees with the file it\njust wrote is evidence of nothing.\n\n## One version stream\n\n**`GATEWAY` and `RUNTIME` stop being release inputs.** `release:prepare` and\n`release:tag` take one version, and `tools/release.sh` loses the two flags.\n\nThey may stay as build-time stamps, because a binary must still report what it\ncontains. A release that must name three versions forces an operator to pass skip\nvalues for components that did not change, and that ceremony is what this decision\nremoves — along with the drift it allows, where two components' tags fall a release\napart.\n\n**Per-component detail stays, as sections inside the release.** A reader still needs\nto know whether `archied` or the agent changed; what goes away is the separate\nnumbers and the separate pages, not the information.\n\n**History is not re-tagged.** Existing tags keep their names, because tags are not a\nsource and nothing reads them to build a page. A future reader must not \"fix\" the\nunified changelog by rewriting tags to match it.\n\n## One release page per version\n\n`docs/news/\u003cversion\u003e.md` replaces `docs/news/\u003ccomponent\u003e/\u003cversion\u003e.md`, carrying the\nrelease's per-component sections inside it.\n\n**Every release URL already published keeps working.** `/news/archied/\u003cversion\u003e` and\n`/news/archie/\u003cversion\u003e` route to the unified page for that version. The generator\nemits the redirect table beside the pages so it cannot drift from them; if the\nrenderer needs the table in its own repository, that is a change in that repository\nrather than a hand-maintained list here.\n\n## The reviewer runs between prepare and tag\n\nRelease notes are prose, and the review agent exists to review prose. **`release:tag`\nrefuses to tag when the review has not been run for that version, or when it reports\nat the level.**\n\nThe invocation is verified rather than assumed. `tl rules --lint` reports `corpus ok`\nand exits 0. `tl review \u003cpath\u003e --deadline \u003cms\u003e --max-turns \u003cn\u003e` reports\n`0 findings (0 high, 0 medium) · 1/1 files reviewed · clean` and exits 0 on\n`docs/news/archied/1.36.0.md`.\n\n**`--fail-on` must be passed explicitly.** It defaults to `never`, so an invocation\nwithout it cannot refuse anything and the step would be decorative. `--fail-on high`\nis the level: a medium finding in a release note is worth acting on, and it should not\nstop a release on its own.\n\n**The rule is stated once.** It belongs in the reviewer's own rule set, which\n`tl rules --from-doc` can draft frLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/review-calibration/",
|
||||
|
||||
@@ -148,6 +148,11 @@ what the commit rules above exist for.
|
||||
- **A breaking change bumps the major version.** Its form is `!` after the type or
|
||||
scope, as in `feat(api)!:`, and a `BREAKING CHANGE:` trailer — either marks it.
|
||||
- `chore`, `docs`, `test`, `style` and `build` bump nothing alone.
|
||||
- **The scope decides whether a commit is the product's.** A commit whose scope is
|
||||
the repository's own machinery -- `release`, `ci`, `docs`, `build`, `test` -- does
|
||||
not bump the version even when its type is `feat` or `fix`, because it changes how
|
||||
the project is delivered rather than what it does. Without this filter the first
|
||||
improvement anyone makes to the release process inflates the product's version.
|
||||
- **No release is a legitimate outcome.** A commit set that justifies no version
|
||||
produces no version, and the pipeline reports that rather than inventing one.
|
||||
|
||||
|
||||
Reference in new issue
Block a user