From 9dae0f0b11b01cfe9a58cd7f660a56f9ad4c32f7 Mon Sep 17 00:00:00 2001 From: sehkone Date: Sat, 8 Aug 2026 09:24:00 +0900 Subject: [PATCH] State the 0.x rule and cut the 0.2.0 changelog MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- CHANGELOG.md | 3 ++- README.md | 10 ++++++++++ 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index dc975de..4f04de3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,7 +7,7 @@ Keep a Changelog change-type headings, so a consumer reads only the sections that affect its template. Version numbers follow the `MAJOR.MINOR.PATCH` policy described in [the README](README.md#versioning). -## Unreleased +## [0.2.0] - 2026-08-08 ### manual @@ -112,4 +112,5 @@ sections that affect its template. Version numbers follow the - Added release workflow to create GitHub Releases from tags using CHANGELOG.md. +[0.2.0]: https://github.com/aicers/docs-theme/tree/0.2.0 [0.1.0]: https://github.com/aicers/docs-theme/tree/0.1.0 diff --git a/README.md b/README.md index 1bc7551..0725ba4 100644 --- a/README.md +++ b/README.md @@ -143,6 +143,16 @@ Templates are **not** versioned separately: one repository version covers all of them, and the vendored diff in a consumer's bump pull request shows whether that consumer is actually affected. +While the version is below `1.0.0`, a breaking change bumps MINOR rather +than MAJOR, and everything else bumps PATCH. The project stays on `0.x` +until the contract above — the install layout, `docs/theme.toml`, +`docs/theme/.meta`, the inherited `mkdocs-base.yml`, the `extra.pdf` +block, and the `build-docs-pdf.sh` interface — has been proven by +consumers actually adopting it. Until then a breaking change is expected +often enough that spending MAJOR on one would drain the signal MAJOR is +meant to carry. `1.0.0` is the point at which "this defines the public +API" describes what happened rather than what is intended. + A release is only meaningful when the installed surface actually changed. The release workflow rejects a tag whose release surface — everything `fetch-theme.sh` installs, plus `fetch-theme.sh` itself — is byte-identical