docs(prds): decide how the merged history represents two dates per version
A version both components released carries one heading and one date: the newest among its sections, because a version's date is when its last part shipped. Where a component's own date differs, that component's section label carries its own, so the per-component fact survives the merge instead of being collapsed into the heading. The ambiguity is historical only -- one version stream with one tag gives a version exactly one date -- so the rule represents the merged past rather than a design that must hold. The same section records how the merge is verified: by content, not by the generator exiting zero. The section count per source, the merged version set equal to the union of both, and every title still present; a generator agreeing with the file it just wrote is evidence of nothing.
This commit is contained in:
1 parent
199b35c3a9
commit
80775676eb
2 files changed
+18
-1
No files matched your search
@@ -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## 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 musLine 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\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 rightLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/review-calibration/",
|
||||
|
||||
@@ -23,6 +23,23 @@ them. The changelog is the only source of release prose, and tags are not a sour
|
||||
CI and deployment check out shallow, so tags are absent from a site build while the
|
||||
changelog is always present.
|
||||
|
||||
### The merged history
|
||||
|
||||
Two version streams become one file, so a version that both components released
|
||||
carries one heading and one date: **the newest date among that version's sections**,
|
||||
because a version's date is when the last part of it shipped. Where a component's own
|
||||
date differs from it, that component's section label carries its own date, so the
|
||||
per-component fact survives the merge rather than being collapsed into the heading.
|
||||
|
||||
This ambiguity is historical only. One version stream with one tag gives a version
|
||||
exactly one date, so the rule represents the merged past rather than a design that has
|
||||
to hold.
|
||||
|
||||
The merge is verified by content, not by the generator succeeding: the section count
|
||||
per source, the merged version set equal to the union of both sources with nothing
|
||||
extra, and every section title still present. A generator that agrees with the file it
|
||||
just wrote is evidence of nothing.
|
||||
|
||||
## One version stream
|
||||
|
||||
**`GATEWAY` and `RUNTIME` stop being release inputs.** `release:prepare` and
|
||||
|
||||
Reference in new issue
Block a user