Changelog Writing
Keep a Changelog format, entry structure, breaking changes, and writing for users
Changelog essentials
- Categories: Added, Changed, Deprecated, Removed, Fixed, Security
- Entry formula: what changed + what was wrong before (for fixes) + issue reference
- Order: newest first — [Unreleased] at top, then latest version, then older
- Audience: end users and integrating developers — write observable behaviour, not implementation
- Breaking changes: old behaviour + new requirement + exact syntax + migration steps
Question 0 of 5
Which changelog entry is written most effectively?
Category + what changed + what was wrong before + issue reference. Changelog entry anatomy:
- Category: "Fixed:" — tells the reader if this affects them
- What changed: "Search results now return correctly when the query contains special characters" — observable behaviour, not implementation detail
- What was wrong: "Previously, queries with these characters returned 0 results" — helps users recognise if they were affected
- Why: "due to unescaped regex input" — enough context to understand the root cause
- Reference: "(Fixes #1842)" — links to the full discussion
Which categories does the "Keep a Changelog" format use?
Added, Changed, Deprecated, Removed, Fixed, Security — the Keep a Changelog standard. What each means:
- Added: new features
- Changed: changes in existing functionality
- Deprecated: features that will be removed in a future version
- Removed: features removed in this version
- Fixed: bug fixes
- Security: vulnerabilities patched — should always be explicitly called out
What should appear at the top of a well-structured changelog?
Most recent entry first — users want to know what just changed. Changelog structure:
- Top: [Unreleased] section (if following Keep a Changelog) — changes not yet released
- Then: most recent release (e.g., [2.4.1] - 2026-05-20)
- Then: older releases in descending order
Who is the primary audience for a public-facing changelog?
End users and dependent developers — not the team. This changes how you write:
- Write in terms of user-observable behaviour, not implementation: ✅ "Search now supports multi-language queries" not ❌ "Added i18n support to SearchService.java"
- Highlight breaking changes clearly — developers integrating your library need to know immediately
- Skip internal refactors, style fixes, and test-only changes — these don't affect the user
- Include migration instructions for breaking changes: "If you used X, replace with Y"
A changelog entry reads: "BREAKING CHANGE: The /users endpoint now requires API version header." What additional information should it include?
Old behaviour + new requirement + exact syntax + migration steps. Complete breaking change entry:
- ❌ "BREAKING CHANGE: The /users endpoint now requires API version header."
- ✅ "BREAKING CHANGE: GET /users now requires the
X-API-Versionheader.
Previously: requests without this header were accepted and defaulted to v1.
Now: requests without this header return 400 Bad Request.
Migration: addX-API-Version: 2to all requests to /users.
If you use our SDK, upgrade to v3.0.0 which adds this header automatically."