Craft

The three questions a changelog must answer

What changed, who noticed, how to roll back. If an entry cannot answer all three, it is a tweet, not a changelog.

Beginner1 min read (computed · recorded 6)updated 2026-09-12changelogwritingprocess

by Motif Editors

revised 2026-09-12 — First publication in bank-3 batch 4.

Key takeaways

— Every entry answers: what changed, who noticed, how to roll back.
— 'Fixed' entries are first-class records, not footnotes.
— The rollback note can be one sentence, but it must exist.

What changed — in user terms

The entry names the module, the user names the symptom. 'Split the demo module behind a loader map' is an internal sentence; 'pages without demos got 315 KB lighter' is the same fact in the reader's currency. This site's changelog carries both, and the measured number is the second one.

Who noticed — the provenance line

Entries that came from feedback say so. It costs one clause, it credits the reporter, and it teaches readers that reporting works. 'Fixed' entries are first-class here, not shame-adjacent footnotes.

How to roll back — the exit

A change worth recording is a change someone may need to undo. The rollback note can be a sentence ('revert the loader map; budgets were re-cut either side'), but it must exist. A changelog without exits is a marketing feed.

Practise the lesson

Theory sticks when you ship it. These original Motif assets put this guide's lesson to work — open one and copy it into your own page.

Changelog Feedpractice Changelog / Journal Templatepractice Changelog Teaserpractice

Keep learning

All guides Try the interactive Lab