diff --git a/RELEASING.md b/RELEASING.md index 9a0a3d07b..64d391865 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -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=` / `RUNTIME=` 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. diff --git a/docs/data/generated/dev-docs.json b/docs/data/generated/dev-docs.json index 0a8d39231..369c24275 100644 --- a/docs/data/generated/dev-docs.json +++ b/docs/data/generated/dev-docs.json @@ -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 from this document; `RELEASING.md` points at that\nrule beside the step it governs rather than restating it, because two statements of\none rule drift.\n\n## Commit rules and their enforcement\n\n- **Conventional commits**, with the scope taken from the package map.\n- **One logical change per commit.** A commit that does two things is two commits.\n- **The subject is imperative and short**; the body says why the change is right\n rather than restating the diff.\n- **A commit depends on the gate's exit status.** The gate and the commit run as one\n conditional chain, never as separate statements on one command line, where nothing\n reads the gate's status but the operator who typed it.\n- **Enforcement is a `commit-msg` hook** installed by one documented target, plus a\n check in CI over the pushed range, so the rule holds for a person who never\n installed the hook.\n- **Scopes are derived, not invented**, and an unknown scope fails loudly rather than\n being accepted.\n\n## The release pipeline\n\n**A Woodpecker workflow performs the release**: gate, generate the release page, run\nthe reviewer over it, commit the changelog and the generated pages, tag, push,\npublish images, and trigger the site's artifact sync. No step in that list is an\noperator's.\n\n**It triggers on a push to main**, not on a manual run. A pipeline a human must start\nis a pipeline that can be forgotten, which is the property this change removes. The\ntrigger is also not dependent on repairing manual triggering: in this estate a manual\nrun fails with zero steps while the same configuration runs on a push, and the\nestate's own Woodpecker configurations trigger on push with cron, manual or\npull-request events *added* to it rather than instead of it.\n\n**Prerequisite: Woodpecker must watch this repository.** Adding the workflow to the\nrepository and enabling the repository in Woodpecker are two steps, and the second is\na configuration action rather than a file. A release pipeline that is correct and\nnever runs is invisible until someone asks why no release happened, so the repository\nbeing enabled is a prerequisite of this design rather than an assumption behind it.\n\n**One tag, and the duplicate-build problem shrinks as a consequence.** Concurrency\nkeyed on a commit identifier treats an annotated tag as a ref distinct from its\ncommit, which starts three builds for one release. One version and one tag removes\ntwo of those refs. Nothing in the pipeline may depend on a tag object's\nidentity, and this is a consequence of one version stream rather than a separate fix.\n\n### The version is computed, not typed\n\nThe version is derived from the conventional commits since the last release, which is\nwhat the commit rules above exist for.\n\n- `feat` bumps the minor version; `fix`, `perf` and `refactor` bump the patch.\n- **A breaking change bumps the major version.** Its form is `!` after the type or\n scope, as in `feat(api)!:`, and a `BREAKING CHANGE:` trailer — either marks it.\n- `chore`, `docs`, `test`, `style` and `build` bump nothing alone.\n- **No release is a legitimate outcome.** A commit set that justifies no version\n produces no version, and the pipeline reports that rather than inventing one.\n\n### `tools/release.sh` is designed for the pipeline\n\n- **It never prompts.** Every input arrives as an argument or in the environment, so\n it runs with no terminal.\n- **Its version is a result as well as an argument.** It may be given one or asked to\n derive one, and it reports the version it used in a form a pipeline can read.\n- **\"Nothing to release\" has its own exit code**, distinct from failure, so the\n pipeline finishes green without tagging.\n- **It commits and tags nothing.** The pipeline owns the commit, the tag and the push;\n the script writes the notes and reports what it did. A script that pushes cannot be\n run twice safely, and this one runs on every push to main.\n\n### Which CI is authoritative\n\nThree surfaces exist: GitHub Actions, the Gitea workflow files, and Woodpecker.\n\n- **Woodpecker owns releases**, which is the production path this repository's deploy\n workflow already names.\n- **GitHub Actions keeps the checks a pull request needs.**\n- **The Gitea workflow files are retired in favour of Woodpecker** once Woodpecker\n runs the same checks, and are not edited in the meantime: two copies of a pipeline\n diverge.\n- No check lives in two places with neither authoritative. Where a check must run in\n both, the second runs the same file rather than a copy of it.\n\n## Verification\n\n- One changelog file exists, the two component changelogs do not, and the generated\n pages match it.\n- A release prepared with `VERSION` alone writes its notes and tags, with no\n `GATEWAY` or `RUNTIME` input.\n- Every release URL published before this change resolves.\n- `release:tag` refuses after a review that reported at the level, and refuses when\n no review ran.\n- The `commit-msg` hook and the CI range check each refuse a non-conforming subject\n and an unknown scope, with the hook absent and present.\n- A push to main carrying releasable commits produces a version, a release page, a\n tag and a published image with no operator step.\n- A push whose commits justify no release ends green and tags nothing.\n- `tools/release.sh` runs to completion with stdin closed, and exits with its\n distinct code when there is nothing to release.\n- The release workflow reads no tag object's identity, so one release starts one\n build.\n" + "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 from this document; `RELEASING.md` points at that\nrule beside the step it governs rather than restating it, because two statements of\none rule drift.\n\n## Commit rules and their enforcement\n\n- **Conventional commits**, with the scope taken from the package map.\n- **One logical change per commit.** A commit that does two things is two commits.\n- **The subject is imperative and short**; the body says why the change is right\n rather than restating the diff.\n- **A commit depends on the gate's exit status.** The gate and the commit run as one\n conditional chain, never as separate statements on one command line, where nothing\n reads the gate's status but the operator who typed it.\n- **Enforcement is a `commit-msg` hook** installed by one documented target, plus a\n check in CI over the pushed range, so the rule holds for a person who never\n installed the hook.\n- **Scopes are derived, not invented**, and an unknown scope fails loudly rather than\n being accepted.\n\n## The release pipeline\n\n**A Woodpecker workflow performs the release**: gate, generate the release page, run\nthe reviewer over it, commit the changelog and the generated pages, tag, push,\npublish images, and trigger the site's artifact sync. No step in that list is an\noperator's.\n\n**It triggers on a push to main**, not on a manual run. A pipeline a human must start\nis a pipeline that can be forgotten, which is the property this change removes. The\ntrigger is also not dependent on repairing manual triggering: in this estate a manual\nrun fails with zero steps while the same configuration runs on a push, and the\nestate's own Woodpecker configurations trigger on push with cron, manual or\npull-request events *added* to it rather than instead of it.\n\n**Prerequisite: Woodpecker must watch this repository.** Adding the workflow to the\nrepository and enabling the repository in Woodpecker are two steps, and the second is\na configuration action rather than a file. A release pipeline that is correct and\nnever runs is invisible until someone asks why no release happened, so the repository\nbeing enabled is a prerequisite of this design rather than an assumption behind it.\n\n**One tag, and the duplicate-build problem shrinks as a consequence.** Concurrency\nkeyed on a commit identifier treats an annotated tag as a ref distinct from its\ncommit, which starts three builds for one release. One version and one tag removes\ntwo of those refs. Nothing in the pipeline may depend on a tag object's\nidentity, and this is a consequence of one version stream rather than a separate fix.\n\n### The version is computed, not typed\n\nThe version is derived from the conventional commits since the last release, which is\nwhat the commit rules above exist for.\n\n- `feat` bumps the minor version; `fix`, `perf` and `refactor` bump the patch.\n- **A breaking change bumps the major version.** Its form is `!` after the type or\n scope, as in `feat(api)!:`, and a `BREAKING CHANGE:` trailer — either marks it.\n- `chore`, `docs`, `test`, `style` and `build` bump nothing alone.\n- **The scope decides whether a commit is the product's.** A commit whose scope is\n the repository's own machinery -- `release`, `ci`, `docs`, `build`, `test` -- does\n not bump the version even when its type is `feat` or `fix`, because it changes how\n the project is delivered rather than what it does. Without this filter the first\n improvement anyone makes to the release process inflates the product's version.\n- **No release is a legitimate outcome.** A commit set that justifies no version\n produces no version, and the pipeline reports that rather than inventing one.\n\n### `tools/release.sh` is designed for the pipeline\n\n- **It never prompts.** Every input arrives as an argument or in the environment, so\n it runs with no terminal.\n- **Its version is a result as well as an argument.** It may be given one or asked to\n derive one, and it reports the version it used in a form a pipeline can read.\n- **\"Nothing to release\" has its own exit code**, distinct from failure, so the\n pipeline finishes green without tagging.\n- **It commits and tags nothing.** The pipeline owns the commit, the tag and the push;\n the script writes the notes and reports what it did. A script that pushes cannot be\n run twice safely, and this one runs on every push to main.\n\n### Which CI is authoritative\n\nThree surfaces exist: GitHub Actions, the Gitea workflow files, and Woodpecker.\n\n- **Woodpecker owns releases**, which is the production path this repository's deploy\n workflow already names.\n- **GitHub Actions keeps the checks a pull request needs.**\n- **The Gitea workflow files are retired in favour of Woodpecker** once Woodpecker\n runs the same checks, and are not edited in the meantime: two copies of a pipeline\n diverge.\n- No check lives in two places with neither authoritative. Where a check must run in\n both, the second runs the same file rather than a copy of it.\n\n## Verification\n\n- One changelog file exists, the two component changelogs do not, and the generated\n pages match it.\n- A release prepared with `VERSION` alone writes its notes and tags, with no\n `GATEWAY` or `RUNTIME` input.\n- Every release URL published before this change resolves.\n- `release:tag` refuses after a review that reported at the level, and refuses when\n no review ran.\n- The `commit-msg` hook and the CI range check each refuse a non-conforming subject\n and an unknown scope, with the hook absent and present.\n- A push to main carrying releasable commits produces a version, a release page, a\n tag and a published image with no operator step.\n- A push whose commits justify no release ends green and tags nothing.\n- `tools/release.sh` runs to completion with stdin closed, and exits with its\n distinct code when there is nothing to release.\n- The release workflow reads no tag object's identity, so one release starts one\n build.\n" }, { "url": "/dev/prds/review-calibration/", diff --git a/docs/prds/release-stream-and-commit-rules.md b/docs/prds/release-stream-and-commit-rules.md index 5aad78e83..a2700bdc7 100644 --- a/docs/prds/release-stream-and-commit-rules.md +++ b/docs/prds/release-stream-and-commit-rules.md @@ -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.