State the 0.x versioning rule and cut the 0.2.0 changelog - #32
Conversation
The Versioning section defined MAJOR, MINOR and PATCH without saying anything about 0.x, and those definitions read as 1.x semantics. Under 0.x a breaking change conventionally bumps MINOR, which nobody could infer from the section as written. The project stays on 0.x because the contract that landed since 0.1.0 — the install layout, docs/theme.toml, .meta, the inherited mkdocs-base.yml, the extra.pdf block, and the build-docs-pdf.sh interface — is self-tested against the samples but has not been proven by a consumer adopting it. bootroot still pins 0.1.0 and runs the old .theme layout. aimer-web builds two configs and already uses exclude_docs for content; agentcoop has neither a PDF build nor a docs/theme.toml. Either could force a base-config change during adoption, and spending MAJOR on that would drain the signal MAJOR exists to carry. The Unreleased entries are promoted unchanged; they were written as each change landed and are already scoped by area. Closes #31
|
Closing in favour of doing this last. Promoting The work is not dropped — #31 stays open and becomes the final step before tagging. The branch Note for whoever picks #31 up: the CHANGELOG promotion is a hard prerequisite for tagging, not a nicety. |
1 participant
Closes #31. Prepares the
0.2.0release; does not create the tag.Why
0.2.0and not1.0.0Everything that makes up the consumer contract landed since
0.1.0— the install layout,docs/theme.toml,docs/theme/.meta, the inheritedmkdocs-base.yml, theextra.pdfblock, and thebuild-docs-pdf.shinterface. All of it is self-tested against the samples, and none of it has been adopted by a consumer:bootrootstill pins0.1.0and runs the old.themelayout.Adoption is where the contract meets cases the samples cannot represent.
aimer-webbuilds two configs and already usesexclude_docsfor content, so the scalar-replacement rule forces it to repeat the base's exclusions. Its PDF has avariantaxis thatextra.pdfdoes not model.agentcoophas neither a PDF build nor adocs/theme.toml. Any of those could force a base-config or layout change, and at1.0.0that is2.0.0within days — spending the "review this against your own documents" signal on teething.0.xis the convention for exactly this state, and nothing practical is lost: pinning, the bump automation, and the release-surface guard all behave identically.1.0.0becomes correct once all four consumers run the model and nothing forced a layout change.Changes
README — the Versioning section defined MAJOR, MINOR, and PATCH but said nothing about
0.x, and those definitions read as1.xsemantics. Adds the0.xrule (breaking bumps MINOR) and states what has to be true before1.0.0. The three definitions themselves are unchanged.CHANGELOG — promotes
## Unreleasedto## [0.2.0] - 2026-08-08and adds the matching link reference. The entries are promoted unchanged: they were written as each change landed and are already scoped by area.Verification
markdownlint-cli2passes; both files stay within MD013's 80 columns.release.yml's extraction logic against the new heading: it resolves## [0.2.0], stops at## [0.1.0], and yields the 15 scoped entries as release notes.Unreleasedheading is left behind.Adjust the date in the heading if the tag lands on a different day.