Version the brand by build date and publish the decision log as the changelog

Context and Problem Statement

A site that consumes the brand needs to know what changed and when, and a version to pin. The brand is a set of decisions, each recorded with a date and the topics it decides. What is a version of the brand, what is its changelog, and how are the sites told?

Decision Drivers

Criteria 1 (trust: traceable change) and 9 (generated and tested) of ADR-0009; ADR-0000 (the records); ADR-0022 (the data carry their date).

Considered Options

• The build date as the version; the decision log by date as the changelog, as JSON
• Semantic versions chosen by hand with a hand-written changelog
• The git history as the only record

Decision Outcome

Proposed: the first option. brand/src/package.ts writes /changelog.json on every build.

• Version. The date of the build, as a calendar version (2026.10.6), carried by the package, tokens.json, units.json, fonts.json, manifest.json and changelog.json. A version is a complete state of the brand, never a loose change.
• Changelog. Every decision record, newest first, with its number, title, status, date, the topics that cite it and its address. What is not a decision is not a brand change; amendments are recorded inside the record they amend, as the records already do.
• Reading it. A site compares its pinned version with the file’s and reads the entries after it; the topics named tell it which tokens or files to look at before it updates.
• Notice. changelog.json is the channel. Once the sites have continuous integration, a daily check against it; an email to the owners goes with every ratification.

Consequences

• Good, because the changelog costs nothing to maintain: it is the decision log the process already produces.
• Good, because version, data and records share one date.
• Open: whether a breaking change (a renamed token) needs a mark beyond the date; a feed besides the JSON.