Changelog Best Practices for SaaS
A changelog is a running record of what changed, for a specific audience. How to decide between a public and internal changelog, what cadence works, a format that scales, whether to follow Keep a Changelog, and how visuals and a feed keep it useful.
A changelog is a complete, chronological record of what changed, written for a defined audience. The first decisions are who it's for (a public changelog for users and prospects, an internal one for the team, usually both) and how often it updates (every user-facing release, with trivial changes batched weekly). The format that scales is a reverse-chronological list grouped by date or version, each entry tagged Added / Changed / Fixed / Removed, with a plain sentence and — for anything users touch — a visual. Follow the Keep a Changelog convention unless you have a reason not to, and publish a feed so people can subscribe.
Public, internal, or both
Most teams should keep both:
- Public changelog — signals an active product, gives support and sales a link, lets prospects see momentum during evaluation. Keep security-fix descriptions vague ("fixed a permissions issue") and omit anything that reveals infrastructure detail.
- Internal changelog — the full picture, including refactors, migrations, and the boring-but-important. This is what a new hire reads to understand recent history.
The public one is a curated subset of the internal one, not a separate effort.
Cadence
- Publish on every user-facing release. If you ship continuously, that means batching.
- Batch the trivia. Ten copy tweaks and two dependency bumps become one "Various small improvements" line, or a single dated entry.
- Don't go dark. Weeks of silence on a public changelog reads as "this product is dying," even when the team is heads-down. If a big project is eating all the cycles, say so in an entry.
Format
Reverse-chronological, grouped by version or date. Each entry categorised — the Keep a Changelog vocabulary is a solid default:
- Added — new features.
- Changed — changes to existing behaviour.
- Deprecated — soon-to-be-removed features.
- Removed — features taken out.
- Fixed — bug fixes.
- Security — vulnerabilities addressed.
Write a human sentence per entry, not just a commit line. "Changed: the export dialog now remembers your last format" beats "Changed: export dialog state persistence."
A changelog and a set of release notes serve different jobs. The changelog is the exhaustive record; release notes are the highlight reel. Don't try to make one document do both — the changelog gets too wordy or the release notes get too long.
Visuals for interactive changes
A one-line entry is fine for a fix or a setting. For anything a user clicks through — a redesigned flow, a new panel, a reworked wizard — a visual carries the change far better than prose. A short interactive walkthrough embedded in the entry lets the reader see the new behaviour without leaving the page:
For lighter changes, a GIF or annotated screenshot does the job.
Make it subscribable
- RSS/Atom feed for the developers and power users who want updates in a reader.
- Email digest — monthly or per-release, for the broader user base.
- In-app "what's new" so logged-in users see it without visiting the page.
Automate the capture
Publishing shouldn't require archaeology. Tag pull requests or commits with a changelog label and a one-line user-facing summary, so assembling the next entry is editing a pre-populated draft rather than reconstructing two weeks of work from memory.
Related: how to write release notes people actually read, how to collect product feedback, and feature adoption.
Frequently asked questions
What is the difference between a changelog and release notes?
A changelog is the ongoing, chronological record of changes — often terse, always complete. Release notes are the curated, user-facing summary of a given release, written to be read. Many teams keep both: a changelog page that lists everything, and release notes or announcements that highlight the items that matter.
Should a SaaS changelog be public?
For most SaaS products, yes — a public changelog signals active development, helps users and prospects see momentum, and gives support a link to point at. Keep security fixes vague in the public version, and maintain a more detailed internal changelog for the team.
What format should a changelog use?
A reverse-chronological list grouped by date or version, with each entry categorised (Added, Changed, Fixed, Removed). The Keep a Changelog convention is a good default. Add a short human sentence per entry rather than only a commit-style line, and include a visual for anything users interact with.
How often should you update a changelog?
Every user-facing release. Batch trivial changes into a weekly entry so the log stays readable, but do not let weeks pass with nothing — a stale changelog reads as a stalled product. Automate the capture of raw changes so publishing is a quick edit, not a research task.