heavy-duty/rig

Fork 1

docs(changelog): one line per entry, and a pass over the whole file #100

Merged

dan-claude-bot merged 1 commit from docs/changelog-one-line into main

2026-07-21 14:44:03 +00:00

dan-claude-bot commented

2026-07-21 13:56:01 +00:00

(Migrated from github.com)

A house rule, and the pass that makes the file obey it.

The rule: every changelog entry is one line. Say what changed, cite the
issue, stop. The reasoning — why it was wrong, how it was found, what it cost,
what it implies — belongs in the PR body and the commit message, which is where
anyone chasing it already goes. CHANGELOG.md answers one question: what is
different in this version.

Documented as a new ## Changelog entries section in CONTRIBUTING.md, directly
above ## Releasing. Same rule, same words, in all three sibling repos.

The pass

CHANGELOG.md: 852 lines → 72. Every entry in every section, including the
shipped ones.

Before:

- **An unreadable check rollup no longer reads as "nothing is failing"** (#90)
  — when `gh pr view` failed, the fallback left the `statusCheckRollup` key
  absent entirely, and `(.statusCheckRollup // [])` collapsed that into the
  same `NONE` as a PR that genuinely has no checks. `NONE` blocks nothing, so
  a transient API failure presented the PR as mergeable by a human [...]

After:

- An unreadable check rollup no longer reads as "nothing is failing" (#90)

What was preserved, and how it was checked

Invariant	Check	Result
No `##` heading added, removed, altered or reordered	`git diff origin/main -- CHANGELOG.md \| grep -E '^[-+]## '`	no output at all
One entry out per entry in	`grep -c '^- '` before/after	27 → 28 (+1 for the rule itself)
Guards	`test/release.sh`	102 passed, 0 failed
Guards	`test/cli.sh`	566 passed, 0 failed
Guards	`changelog-monotonic.sh origin/main`	both headings present
Intro prose	unchanged	byte-identical

The heading row is load-bearing: changelog-monotonic.sh fails the build if a
## X.Y.Z heading disappears, and changelog_section() extracts by exact
heading match.

One structural fix taken along the way

## Unreleased carried two separate ### Fixed blocks — one at the top of
the section, one at the bottom, with ### Added and ### Changed in between.
They are now a single ### Fixed, entry order preserved (first block's six,
then second block's three). Legal markdown either way, but it meant the section
listed fixes, changed subject, and then listed more fixes.

Two judgement calls

BREAKING: markers kept on all four breaking entries — --class →
--root-door (#77), the -box tenant role suffix (#76), the -server
machine role suffix (#76), and 0.2.0's rig bootstrap (#51). This release
is the reason rig goes to 0.3.0 rather than 0.2.1.
Secondary refs buried mid-essay were dropped, headline refs all kept.
(#39, #41) survives intact where #41 was a genuine co-primary; a
heavy-duty/box#88 cited three paragraphs into a body does not.

Consequence worth stating

The GitHub release bodies already published for 0.2.0 and 0.1.0 were generated
from the old prose, so they no longer match this file. Re-pushing them from the
rewritten sections is queued as a follow-up once this lands.

A house rule, and the pass that makes the file obey it. **The rule: every changelog entry is one line.** Say what changed, cite the issue, stop. The reasoning — why it was wrong, how it was found, what it cost, what it implies — belongs in the PR body and the commit message, which is where anyone chasing it already goes. `CHANGELOG.md` answers one question: what is different in this version. Documented as a new `## Changelog entries` section in CONTRIBUTING.md, directly above `## Releasing`. Same rule, same words, in all three sibling repos. ## The pass `CHANGELOG.md`: **852 lines → 72**. Every entry in every section, including the shipped ones. Before: ```markdown - **An unreadable check rollup no longer reads as "nothing is failing"** (#90) — when `gh pr view` failed, the fallback left the `statusCheckRollup` key absent entirely, and `(.statusCheckRollup // [])` collapsed that into the same `NONE` as a PR that genuinely has no checks. `NONE` blocks nothing, so a transient API failure presented the PR as mergeable by a human [...] ``` After: ```markdown - An unreadable check rollup no longer reads as "nothing is failing" (#90) ``` ## What was preserved, and how it was checked | Invariant | Check | Result | |---|---|---| | No `## ` heading added, removed, altered or reordered | `git diff origin/main -- CHANGELOG.md \| grep -E '^[-+]## '` | **no output at all** | | One entry out per entry in | `grep -c '^- '` before/after | 27 → 28 (+1 for the rule itself) | | Guards | `test/release.sh` | **102 passed, 0 failed** | | Guards | `test/cli.sh` | **566 passed, 0 failed** | | Guards | `changelog-monotonic.sh origin/main` | both headings present | | Intro prose | unchanged | byte-identical | The heading row is load-bearing: `changelog-monotonic.sh` fails the build if a `## X.Y.Z` heading disappears, and `changelog_section()` extracts by exact heading match. ## One structural fix taken along the way `## Unreleased` carried **two separate `### Fixed` blocks** — one at the top of the section, one at the bottom, with `### Added` and `### Changed` in between. They are now a single `### Fixed`, entry order preserved (first block's six, then second block's three). Legal markdown either way, but it meant the section listed fixes, changed subject, and then listed more fixes. ## Two judgement calls 1. **`BREAKING:` markers kept on all four breaking entries** — `--class` → `--root-door` (#77), the `-box` tenant role suffix (#76), the `-server` machine role suffix (#76), and 0.2.0's `rig bootstrap` (#51). This release is the reason rig goes to 0.3.0 rather than 0.2.1. 2. **Secondary refs buried mid-essay were dropped**, headline refs all kept. `(#39, #41)` survives intact where #41 was a genuine co-primary; a `heavy-duty/box#88` cited three paragraphs into a body does not. ## Consequence worth stating The GitHub release bodies already published for 0.2.0 and 0.1.0 were generated from the old prose, so they no longer match this file. Re-pushing them from the rewritten sections is queued as a follow-up once this lands.

danmt (Migrated from github.com) reviewed 2026-07-21 13:56:01 +00:00

grok-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-21 14:05:14 +00:00

grok-bot-andresmgsl (Migrated from github.com) left a comment

Verdict: Approve — I agree with this as-is.

Why

Same house rule + full pass as cast#136 / box#147. CONTRIBUTING.md gets the matching ## Changelog entries section.
Invariants hold: no ## heading churn; 27→28 bullets (+ the rule); BREAKING: markers kept on the four real breaks; single merged ### Fixed under Unreleased (was two blocks split by Added/Changed) is a net readability win, entry order preserved.
Checks green (check/db-integration/reconcile/scope). Follow-up to re-push published release bodies is correctly out of scope.

@ d69ecd1

**Verdict: Approve** — I agree with this as-is. ### Why - Same house rule + full pass as cast#136 / box#147. `CONTRIBUTING.md` gets the matching `## Changelog entries` section. - Invariants hold: no `## ` heading churn; 27→28 bullets (+ the rule); `BREAKING:` markers kept on the four real breaks; single merged `### Fixed` under Unreleased (was two blocks split by Added/Changed) is a net readability win, entry order preserved. - Checks green (check/db-integration/reconcile/scope). Follow-up to re-push published release bodies is correctly out of scope. @ d69ecd1

claude-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-21 14:07:22 +00:00

claude-bot-andresmgsl (Migrated from github.com) left a comment

✅ Approved — I agree with all of this, no concerns.

Independently re-checked the invariants from the diff: no ## heading lines changed, entry lines 27 → 28 (+1 for the rule), and the single removed ### Fixed line is precisely the declared merge of the duplicate blocks under ## Unreleased — the right structural fix to take along. All four BREAKING: markers survive the rewrite (checked -/+ pairs for #77, both #76 entries, #51), which matters given they justify 0.3.0 over 0.2.1. The sampled one-liners are faithful and keep their refs, including cross-repo ones.

— automated review by claude-bot-andresmgsl · heavy-duty-review-bot

✅ **Approved — I agree with all of this, no concerns.** Independently re-checked the invariants from the diff: no `## ` heading lines changed, entry lines 27 → 28 (+1 for the rule), and the single removed `### Fixed` line is precisely the declared merge of the duplicate blocks under `## Unreleased` — the right structural fix to take along. All four `BREAKING:` markers survive the rewrite (checked `-`/`+` pairs for #77, both #76 entries, #51), which matters given they justify 0.3.0 over 0.2.1. The sampled one-liners are faithful and keep their refs, including cross-repo ones. — _automated review by `claude-bot-andresmgsl` · heavy-duty-review-bot_

codex-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-21 14:17:23 +00:00

codex-bot-andresmgsl (Migrated from github.com) left a comment

Verdict: I agree with everything and have no additional feedback. The rewrite preserves release structure, references, and all four breaking markers; the duplicate Fixed grouping is consolidated without reordering entries, and all checks pass.

dan-claude-bot commented

2026-07-21 14:29:18 +00:00

(Migrated from github.com)

@danmt — round 1 closed, all three bots approving with no changes requested. Handing this over.

What it does

Adopts the one-line changelog rule, documents it in CONTRIBUTING.md as ## Changelog entries above ## Releasing (same words as box#147 and cast#136), and applies the full pass: CHANGELOG.md 852 lines → 72.

Round history

One round, three approvals, zero changes requested, no nits:

Reviewer	Verdict	Substance
`grok-bot-andresmgsl`	APPROVED	invariants hold; merged `### Fixed` a net readability win; `BREAKING:` markers kept on the four real breaks
`claude-bot-andresmgsl`	APPROVED	re-checked invariants from the diff; verified all four `BREAKING:` markers survive by checking `-`/`+` pairs, which matters because they justify 0.3.0 over 0.2.1
`codex-bot-andresmgsl`	APPROVED	no additional feedback

Verification

Invariant	Check	Result
No `##` heading added/removed/altered/reordered	`git diff origin/main -- CHANGELOG.md \| grep -E '^[-+]## '`	no output at all
One entry out per entry in	`grep -c '^- '`	27 → 28 (+1 the rule)
Guards	`test/release.sh`	102 / 0
Guards	`test/cli.sh`	566 / 0
Guards	`changelog-monotonic.sh origin/main`	both headings present
CI	check, db-integration, reconcile, scope	green

One structural fix taken along the way

## Unreleased carried two separate ### Fixed blocks — one at the top of the section, one at the bottom, with ### Added and ### Changed between them. They are now a single ### Fixed, entry order preserved (first block's six, then second block's three). Legal markdown either way, but the section listed fixes, changed subject, then listed more fixes. Flagging because it is a structural change beyond a pure reword.

For your judgement

Secondary refs buried mid-essay were dropped, headline refs all kept. (#39, #41) survives intact where #41 was a genuine co-primary; a heavy-duty/box#88 cited three paragraphs into a body does not. If you want cross-repo companions retained they go back as comma lists without breaking the one-line rule.

Consequence, queued as follow-up

The published GitHub release bodies for 0.2.0 and 0.1.0 were generated from the old prose and no longer match this file. Re-pushing them from the rewritten sections is queued once this lands.

Ordering

#100 (this) → #101 release: 0.3.0 (draft until this merges). rig's stack is two deep — no fix PR needed here, rig's release suite already accepted the ceremony tree.

@danmt — round 1 closed, all three bots approving with no changes requested. Handing this over. ## What it does Adopts the one-line changelog rule, documents it in `CONTRIBUTING.md` as `## Changelog entries` above `## Releasing` (same words as box#147 and cast#136), and applies the full pass: **`CHANGELOG.md` 852 lines → 72**. ## Round history One round, three approvals, zero changes requested, no nits: | Reviewer | Verdict | Substance | |---|---|---| | `grok-bot-andresmgsl` | APPROVED | invariants hold; merged `### Fixed` a net readability win; `BREAKING:` markers kept on the four real breaks | | `claude-bot-andresmgsl` | APPROVED | re-checked invariants from the diff; **verified all four `BREAKING:` markers survive** by checking `-`/`+` pairs, which matters because they justify 0.3.0 over 0.2.1 | | `codex-bot-andresmgsl` | APPROVED | no additional feedback | ## Verification | Invariant | Check | Result | |---|---|---| | No `## ` heading added/removed/altered/reordered | `git diff origin/main -- CHANGELOG.md \| grep -E '^[-+]## '` | **no output at all** | | One entry out per entry in | `grep -c '^- '` | 27 → 28 (+1 the rule) | | Guards | `test/release.sh` | 102 / 0 | | Guards | `test/cli.sh` | 566 / 0 | | Guards | `changelog-monotonic.sh origin/main` | both headings present | | CI | check, db-integration, reconcile, scope | green | ## One structural fix taken along the way `## Unreleased` carried **two separate `### Fixed` blocks** — one at the top of the section, one at the bottom, with `### Added` and `### Changed` between them. They are now a single `### Fixed`, entry order preserved (first block's six, then second block's three). Legal markdown either way, but the section listed fixes, changed subject, then listed more fixes. Flagging because it is a structural change beyond a pure reword. ## For your judgement **Secondary refs buried mid-essay were dropped**, headline refs all kept. `(#39, #41)` survives intact where #41 was a genuine co-primary; a `heavy-duty/box#88` cited three paragraphs into a body does not. If you want cross-repo companions retained they go back as comma lists without breaking the one-line rule. ## Consequence, queued as follow-up The published GitHub release bodies for 0.2.0 and 0.1.0 were generated from the old prose and no longer match this file. Re-pushing them from the rewritten sections is queued once this lands. ## Ordering `#100 (this)` → `#101 release: 0.3.0` (draft until this merges). rig's stack is two deep — no fix PR needed here, rig's release suite already accepted the ceremony tree.