Write a changelog

The recipe for the record of change — dated, categorized entries that flag breakage and deep-link into the docs. Checklist and a scaffold command.

Oct 18, 2026

When to use it

One changelog per product (or per clearly versioned surface). Two load-bearing distinctions:

Record vs. policy: dated entries of what changed live here; how versioning works and how to migrate live on their own pages, linked from every breaking entry.
Two genres, pick by what the reader keys on:
- Date-headed — for a continuously shipped product surface. Sections per release date; entries titled by the change.
- Version-headed — for a versioned artifact (an SDK, a named API version): sections per version (## [2.14.0] — 2026-06-18, plus an Unreleased section for libraries). The entry rules below apply within each version section. The maintainer’s question “what changed between 2.13 and 2.14?” is unanswerable in a date-headed log — if readers pin versions, head by version.

The changelog is not:

A commit log. A changelog is written for humans (and now agents) — curated, benefit-first entries, not a dump of merge messages. If a change isn’t worth explaining, it isn’t worth listing.
Release marketing. A launch post persuades; a changelog entry informs. Link the launch post from the entry if it exists — don’t replace the entry with it.
A migration guide. An entry says that something breaks and links out; the step-by-step of migrating is a how-to (or a dedicated migration guide for big ones).

Title & description

Page title: “Changelog” — the fixed, expected string.
Entry titles: the change itself, specific and self-contained. “Retry backoff is now configurable per endpoint” — not “Improvements to delivery” (says nothing) and not a bare version number (versions head sections, not entries).
Description formula (page): “Every notable change to product, dated, with breaking changes flagged.”

Scaffold this page

Install the recipe — your coding agent reads the full skeleton and checklist and adapts them to your product:

npx @cloudflare/nimbus-docs add content-changelog

yarn nimbus-docs add content-changelog

pnpm nimbus-docs add content-changelog

bunx @cloudflare/nimbus-docs add content-changelog

Component guidance

Section headings (date or version) + entry sub-headings are the structure. The breaking flag opens the entry body in bold (**Deprecated · Breaking, effective 2026-09-18**) — first thing scanners and feed readers see, without polluting the heading’s anchor. In rendered pages a Badge component on the heading line can echo it.
Category labels (the six standard categories: Added / Changed / Deprecated / Removed / Fixed / Security) as consistent bold prefixes — they make the page filterable by eye and by machine.
Doesn’t fit: Steps (migration steps live in the linked guide), Cards, screenshots (link the docs that show the new UI instead — screenshots in a changelog rot in place forever).

Ending

A changelog doesn’t end; it accumulates. The contract sits at the top (policy link, subscription channels) and in each entry (links to the pages describing the new state).

Never rewrite a published entry silently. If one turns out wrong, such as an unflagged breaking change, amend it and publish a dated correction, so readers scanning by version and by date both see it.

Thresholds

Entry body ≤ 3 sentences. Depth beyond that lives on a linked detail page, migration guide, or launch post.
Entries that change documented behavior link to the updated docs page. Fixed and Security entries link to the relevant reference or troubleshooting page when one exists — a fix for behavior the docs never documented has nowhere to point, and that’s fine.
Every breaking/deprecation entry carries: who’s affected, what to do, and a date. Missing any of the three, it isn’t ready to publish.

Links & freshness

Entries deep-link into stable doc anchors, one more reason reference anchors never move. Entry headings are permalinks too, so keep them stable.

Publishing an entry and updating the pages it links to is one act. An entry announcing a field the reference doesn’t show yet documents a product that doesn’t exist.

Agent notes

The changelog is the prior-correction surface: deprecated things live on in training data, so Deprecated/Removed entries are what stop an agent from recommending them. Write them as flat declaratives an agent can act on: “attempt_count is deprecated; use attempt.”
Dates in ISO format (2026-06-18); “last month” is meaningless in a retrieved chunk.
Each entry self-contained: full field names, full feature names — an entry retrieved alone must make sense alone.
Personality never replaces the fact. Whimsy without specifics is a non-statement no reader or agent can act on; if you want voice, add it after the fact, not instead of it.

Checklist

Advisory — self-review for author or agent, never a build gate:

Edit this page