Style guide — changelog

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 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.

[edit]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.

[edit]Structure

The changelog is a flat list of version blocks, newest at the top:

## M.m.P — YYYY-MM-DD

- <one-line entry, reader-facing>
- <one-line entry, reader-facing>

## M.m.P-1 — YYYY-MM-DD

- <one-line entry, reader-facing>

Each version block:

• 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."
• 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.

[edit]What counts as a changelog entry

Include:

• New capabilities available to consumers.
• Breaking changes to the public surface.
• Significant bug fixes with user-visible impact.
• Major structural changes (module split, rename).

Exclude:

• Internal refactors with no consumer-visible effect.
• Test additions or CI changes.
• Documentation-only commits (these are implicit in the version date).
• Version-bump commits (the heading captures this).

[edit]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.

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.

[edit]See also

• Style Guide — README
• Style Guide — ARCHITECTURE
• Language Protocol Substrate