Amey-Thakur Changelog writing
A changelog tells users what changed and what they must do about it. It is written for the human deciding whether and how to upgrade, not for the machine that generated the commits: a dump of commit subjects is not a changelog, it is a diff with worse formatting.
Method
- Write for the upgrader's decision. The reader is asking "should I upgrade, and what breaks if I do": lead with what affects them (breaking changes, new capabilities, fixes to bugs they hit), in their language, not internal commit-speak. "Refactored the auth module" means nothing to a user; "Sessions now expire after 24h (was 7 days)" tells them what to do.
- Group by type, newest version first. The keep-a-changelog convention: per version, sections for Added, Changed, Deprecated, Removed, Fixed, Security: so a reader scans to the category they care about. A flat chronological list forces reading everything to find the breaking change buried in the middle.
- Call out breaking changes loudly, with migration. Breaking changes get a prominent marker and a "how to migrate" note (see api-versioning, api-change-management): this is the single most important entry for anyone upgrading, and burying it causes broken deployments. If there is one thing the changelog gets right, it is this.
- Date every version, link the details. Release date per version, version numbers matching the tags (see release-tagging, semver), and links to issues/PRs for readers who want the full story: the changelog is the summary, the linked items are the depth (see readme-writing's lean-and-link ethic).
- Generate the draft, curate the result. Structured commits (conventional-commits: see commit-messages) let tooling draft the changelog grouped by type; then a human edits for the user's perspective (merging noise, writing the migration notes, promoting what matters): generated-then-curated is complete without being a commit dump. Pure generation lists every "fix typo"; pure hand-writing omits things.
- Keep an Unreleased section, update as you go. Add entries when the change lands (in the same PR: see docs-as-code), accumulating under Unreleased, promoted to a version on release: so the changelog is never a scramble at release time and never forgets a change made three weeks ago.
Boundaries
- The changelog is the technical record of changes; marketing release notes and launch announcements (see product-launch) are a different, audience-shaped document that may draw from it.
- Internal-only changes (refactors, test additions) that do not affect users can be omitted or minimized; the changelog serves users, not a complete audit of activity (that is git history: see git-history-hygiene).
- Automated changelog tooling is only as good as commit discipline; adopt it when the team's commit messages are reliable, curate always (see commit-messages).