Skip to content

Align the changelog with the house format and cut 0.3.0 - #42

Merged
sehkone merged 1 commit into
mainfrom
sehkone/issue-41
Aug 8, 2026
Merged

Align the changelog with the house format and cut 0.3.0#42
sehkone merged 1 commit into
mainfrom
sehkone/issue-41

Conversation

@sehkone

@sehkone sehkone commented Aug 8, 2026

Copy link
Copy Markdown
Contributor

Closes #41. Last step before tagging 0.3.0; does not create the tag.

The format had drifted

CHANGELOG.md no longer matched what bootroot and agentcoop use. Three deviations, all introduced when the area-scoped convention was adopted:

house format docs-theme before
header Keep a Changelog + SemVer blurb a note explaining the local convention
sections ### Added / Changed / Fixed / Removed ### manual / api-reference / shared / scripts
link refs compare/<prev>...<ver> tree/<ver>

The header is now byte-identical to bootroot's. 0.1.0's section already used ### Added, so only 0.2.0 and 0.3.0 needed re-bucketing.

The area grouping duplicated itself. Nine bullets under 0.2.0 appeared verbatim under both manual and api-reference, because a change affecting both templates had to be written twice. Collapsing that is most of why this is 93 insertions against 148 deletions while losing no information.

Buckets follow what each entry describes, not which release it landed in — the dropped chapter content, the unruled PDF tables, and the assets that never reached the published site are Fixed, not Changed.

0.2.0's published release notes are unaffected: they were extracted at tag time and live on the release page.

Also in here

  • Promotes ## Unreleased to ## [0.3.0] - 2026-08-08 — consumed, not left behind as an empty section, which is what agentcoop's release commits do (-## [Unreleased] / +## [0.9.0] - 2026-07-22). This is the prerequisite for tagging — release.yml greps ^## \[$VERSION\], so a tag against a bare Unreleased makes Release for version 0.3.0 the entire release body, and that is what the Slack subscription posts.
  • Brings SURFACE_PATHS in check-release-surface.sh back in step with the installer. fetch-theme.sh gained brand-print.svg and brand-symbol.svg; the guard still listed only brand.svg, so a later release changing just those two would have compared byte-identical and been rejected with "nothing for consumers to fetch". It fails closed rather than open, so it was not urgent — but it is wrong, and it is two lines.

That list has to be kept in step with the installer by hand. Worth a follow-up to derive one from the other, or to assert the correspondence in installer-test.sh.

Verification

  • Header diffed byte-for-byte against bootroot's: identical.
  • Section headings are now exactly Added, Changed, Fixed, Removed. Repeated across releases is fine — the root config sets MD024: siblings_only.
  • Ran release.yml's extraction against the new heading: resolves ## [0.3.0], stops at ## [0.2.0], yields 7 entries under Added and Changed.
  • Ran the guard's own comparison directly (git diff 0.2.0 HEAD over SURFACE_PATHS): the surface differs, so the tag will pass. Running check-release-surface.sh 0.3.0 locally reports "No predecessor tag" and skips — it resolves the predecessor by locating the new tag in the existing tag list, which only works once the tag exists. CI runs it after the tag is pushed.
  • markdownlint-cli2 and shellcheck clean. One line exceeds 80 columns — the SemVer link in the inherited house header; MD013 does not flag it because the overrun is an unbreakable URL.

Adjust the date in the heading if the tag lands on a different day.

@sehkone sehkone changed the title Cut the 0.3.0 changelog Align the changelog with the house format and cut 0.3.0 Aug 8, 2026
The file had drifted from the format bootroot and agentcoop use, in
three ways. The header replaced the Keep a Changelog and Semantic
Versioning blurb with a note explaining a local convention. Entries were
grouped by the area a consumer triages -- manual, api-reference, shared,
scripts -- rather than by change type. Link references pointed at tree/
rather than compare/.

The area grouping also duplicated: nine bullets under 0.2.0 appeared
verbatim under both manual and api-reference, because a change to both
templates had to be written twice. Grouping by change type instead
removes that, which is most of why this rewrite is shorter than what it
replaces.

Buckets follow what the entries describe rather than which release they
landed in, so the dropped chapter content, the unruled PDF tables, and
the assets that never reached the published site are Fixed rather than
Changed.

0.2.0's published release notes are unaffected; they were extracted at
tag time and live on the release page.

Also promotes Unreleased to 0.3.0, and brings SURFACE_PATHS in
check-release-surface.sh back in step with the installer: fetch-theme.sh
gained brand-print.svg and brand-symbol.svg, so a later release changing
only those would have compared byte-identical and been rejected with
nothing to release.

Closes #41
@sehkone
sehkone merged commit 31cc482 into main Aug 8, 2026
6 checks passed
@sehkone
sehkone deleted the sehkone/issue-41 branch August 8, 2026 07:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Cut the 0.3.0 changelog

1 participant