Diff: reference/style-guide-changelog
From 2169822 to 2169822
+0 / −0 lines
| Before | After |
|---|---|
| --- | --- |
| schema: foundry-doc-v1 | schema: foundry-doc-v1 |
| title: "Style guide — changelog" | title: "Style guide — changelog" |
| slug: style-guide-changelog | slug: style-guide-changelog |
| category: reference | category: reference |
| type: topic | type: topic |
| quality: complete | quality: complete |
| short_description: "Editorial standards for CHANGELOG.md files in platform repositories: versioning discipline, entry format, newest-first ordering, and the distinction between a changelog and a commit log." | short_description: "Editorial standards for CHANGELOG.md files in platform repositories: versioning discipline, entry format, newest-first ordering, and the distinction between a changelog and a commit log." |
| status: active | status: active |
| bcsc_class: public-disclosure-safe | bcsc_class: public-disclosure-safe |
| last_edited: 2026-05-24 | last_edited: 2026-05-24 |
| editor: pointsav-engineering | editor: pointsav-engineering |
| cites: [] | cites: [] |
| paired_with: style-guide-changelog.es.md | paired_with: style-guide-changelog.es.md |
| --- | --- |
| > A changelog answers one question for every version: what changed, stated in one line, from the reader's point of view. | > A changelog answers one question for every version: what changed, stated in one line, from the reader's point of view. |
| A **CHANGELOG.md** records meaningful changes to a repository at each version boundary. It is addressed to a reader who wants to know what a new version contains without reading a diff. A changelog is not a commit log — it selects, compresses, and reframes the commit history for a consumer who cares about impact, not implementation. The [[root-files-discipline|root files discipline]] governs when a CHANGELOG.md is required. This article is the human-facing standard; the machine-readable counterpart lives in `service-disclosure/templates/changelog.toml`. | A **CHANGELOG.md** records meaningful changes to a repository at each version boundary. It is addressed to a reader who wants to know what a new version contains without reading a diff. A changelog is not a commit log — it selects, compresses, and reframes the commit history for a consumer who cares about impact, not implementation. The [[root-files-discipline|root files discipline]] governs when a CHANGELOG.md is required. This article is the human-facing standard; the machine-readable counterpart lives in `service-disclosure/templates/changelog.toml`. |
| ## When to use this template | ## When to use this template |
| Every repository that carries version numbers uses a `CHANGELOG.md`. The file is created when the first meaningful entry exists — not as a placeholder. Repositories that do not version (pure content stores without a semantic version) may omit it; they track meaningful changes in `NEXT.md` or `cleanup-log.md`. | Every repository that carries version numbers uses a `CHANGELOG.md`. The file is created when the first meaningful entry exists — not as a placeholder. Repositories that do not version (pure content stores without a semantic version) may omit it; they track meaningful changes in `NEXT.md` or `cleanup-log.md`. |
| ## Structure | ## Structure |
| The changelog is a flat list of version blocks, newest at the top: | The changelog is a flat list of version blocks, newest at the top: |
| ```markdown | ```markdown |
| ## M.m.P — YYYY-MM-DD | ## M.m.P — YYYY-MM-DD |
| - <one-line entry, reader-facing> | - <one-line entry, reader-facing> |
| - <one-line entry, reader-facing> | - <one-line entry, reader-facing> |
| ## M.m.P-1 — YYYY-MM-DD | ## M.m.P-1 — YYYY-MM-DD |
| - <one-line entry, reader-facing> | - <one-line entry, reader-facing> |
| ``` | ``` |
| Each version block: | Each version block: |
| - Heading level `##`. Version number and ISO 8601 date on the same line. | - Heading level `##`. Version number and ISO 8601 date on the same line. |
| - One bullet per meaningful change. Bullets are reader-facing: describe the effect, not the mechanism. "Adds X" rather than "Implemented the X module." | - One bullet per meaningful change. Bullets are reader-facing: describe the effect, not the mechanism. "Adds X" rather than "Implemented the X module." |
| - Grouping labels (`### Added`, `### Fixed`, `### Changed`) are permitted when a version has more than five entries. Omit them when a version has five or fewer — grouping adds noise below that threshold. | - Grouping labels (`### Added`, `### Fixed`, `### Changed`) are permitted when a version has more than five entries. Omit them when a version has five or fewer — grouping adds noise below that threshold. |
| ## What counts as a changelog entry | ## What counts as a changelog entry |
| Include: | Include: |
| - New capabilities available to consumers. | - New capabilities available to consumers. |
| - Breaking changes to the public surface. | - Breaking changes to the public surface. |
| - Significant bug fixes with user-visible impact. | - Significant bug fixes with user-visible impact. |
| - Major structural changes (module split, rename). | - Major structural changes (module split, rename). |
| Exclude: | Exclude: |
| - Internal refactors with no consumer-visible effect. | - Internal refactors with no consumer-visible effect. |
| - Test additions or CI changes. | - Test additions or CI changes. |
| - Documentation-only commits (these are implicit in the version date). | - Documentation-only commits (these are implicit in the version date). |
| - Version-bump commits (the heading captures this). | - Version-bump commits (the heading captures this). |
| ## Register and tone | ## Register and tone |
| Plain. Active voice, present tense: "Adds support for X", "Fixes the Y parsing failure." Not "We've added" or "This version includes." Not "Various improvements" — name what changed. | Plain. Active voice, present tense: "Adds support for X", "Fixes the Y parsing failure." Not "We've added" or "This version includes." Not "Various improvements" — name what changed. |
| Sentence-length budget: one line per entry, target under twenty words. The date on the version heading uses ISO 8601 (`YYYY-MM-DD`). The version number follows the workspace versioning rule (MAJOR.MINOR.PATCH per workspace §7): PATCH increments per accepted commit; MINOR increments per feature milestone. | Sentence-length budget: one line per entry, target under twenty words. The date on the version heading uses ISO 8601 (`YYYY-MM-DD`). The version number follows the workspace versioning rule (MAJOR.MINOR.PATCH per workspace §7): PATCH increments per accepted commit; MINOR increments per feature milestone. |
| ## See also | ## See also |
| - [[style-guide-readme|Style Guide — README]] | - [[style-guide-readme|Style Guide — README]] |
| - [[style-guide-architecture|Style Guide — ARCHITECTURE]] | - [[style-guide-architecture|Style Guide — ARCHITECTURE]] |
| - [[language-protocol-substrate|Language Protocol Substrate]] | - [[language-protocol-substrate|Language Protocol Substrate]] |