Changelog template
A changelog is a reverse-chronological list of what changed and why it matters. Ask your agent to draft it and share a link — users comment on the exact entry, instead of asking 'wait, when did you ship that?'
Most changelogs die in a Slack message that scrolls away in 20 minutes or an email no one opens a week late. The format is simple. The failure mode is always distribution: the update exists somewhere, but users never find it.
Draft it with your agent
Paste this into Claude, Cursor, or any agent — it drafts the changelog entry and publishes it as a Drafty link:
See it on a real one
What goes in a changelog entry
One entry, four things:
- Date and version — when it shipped and what version it is. Use ISO format (2025-01-15) to avoid ambiguity — 01/12 means different things in different countries.
- Category label — Added, Fixed, Changed, Deprecated, or Removed. Readers scan labels; don't make them read prose to figure out if something broke.
- What changed — one line, starting with an action verb. "Added CSV export to the reports page" is correct. "We have now introduced the ability for users to export" is not.
- Why it matters — one sentence of context. Teams that skip this find their support queue filling with "what does this mean?" tickets the day after shipping.
The most common mistake: writing the changelog for your commit log instead of your users. "Fixed edge case in auth token refresh" is a git commit message. "Fixed a bug that logged some users out unexpectedly on mobile" is a changelog entry.
The section most changelogs skip
Include a short "not in this release" note for anything users were expecting. If you deferred a requested feature, saying "the bulk export feature is coming in the next release" takes five seconds and saves a dozen support questions. The absence of a thing people expected is news too.
When to publish
Publish the changelog the day the release ships, not two weeks later. The closer the announcement is to the moment users notice the change, the less likely they are to file a confused support ticket. If you ship continuously, batch entries weekly — a dated weekly summary beats a daily noise stream.
Share the Drafty link in your product's in-app notification, your release email, or your team Slack. Comments anchor to the exact entry — "does this fix the timeout issue I reported?" lands on that line, not floating in a reply thread.
FAQ
What's the difference between a changelog and release notes?
A changelog is the complete, ongoing record — every entry, in reverse chronological order, going back to day one. Release notes are the announcement for one specific release, written for non-technical users and often including screenshots or migration steps. A changelog is the archive; release notes are the press release.
How often should I update the changelog?
Once per release, or weekly if you ship continuously. The mistake is batching entries so long that a single changelog post covers two months of changes — by then users have already filed support tickets about the things they didn't notice.
What should I not include in a changelog?
Internal tooling changes, refactors that don't affect behavior, and anything the user can't observe. Also skip the corporate PR tone — "exciting new update!" reads worse than silence. Write for the person who just noticed something different and wants to understand it in ten seconds.
How do I write a good changelog entry?
Start with an action verb (Added, Fixed, Changed). Describe the observable change, not the implementation. Add one sentence of "why" if the change might be confusing without context. Keep each entry to two sentences max — if it needs more, link to a doc.
Does every project need a changelog?
Any project with external users or teammates who depend on it benefits from one. Open-source libraries follow the Keep a Changelog convention almost universally. SaaS products and internal tools often skip it — and then wonder why users keep asking about features that shipped months ago.
Can my agent maintain the changelog for me?
Yes — and it's one of the highest-ROI things to automate. Point your agent at the diff or the release ticket, paste the prompt above, and it will draft the entry in the right format. You review, edit the "why" sentence to match your users' language, and publish. The agent handles structure; you handle judgment.