Changelog best practices for SaaS
Most SaaS changelogs die the same death: enthusiastic start, three months of entries, then a gap that makes the product look abandoned. The practices below are less about writing well and more about building a changelog that survives busy quarters — because a changelog's main job is being reliably there.
Pick one format and never deviate
Readers scan changelogs; scanning only works when every entry has the same shape. The reference standard is keepachangelog.com: reverse-chronological, grouped by release, entries categorized Added / Changed / Deprecated / Removed / Fixed / Security.
For a user-facing SaaS changelog, most teams simplify to New / Improved / Fixed — the trade-offs versus a full technical record are covered in changelog vs. release notes. Either is fine. Switching between them isn't.
Write entries for users, not for the git log
An entry is not a commit message. Beamer's practices list and Recaip's rules converge on the same entry anatomy: a bold one-line summary of the change, then one to three sentences on impact — what it does for the user, not how it was implemented. Highlight only changes that affect users; the full commit history belongs in the repo.
Group by type, not by team
"Billing team updates" is your org chart leaking into your changelog. Readers care whether something is new, improved, or fixed — never which squad shipped it.
Be honest in the Fixed section
"Minor fixes and improvements" is the entry that teaches readers to stop reading. Name the bug: "Fixed an issue where webhook retries fired twice." The users who hit the bug are the most motivated readers a changelog has, and specific fix entries are how a changelog earns trust. This matters double for feature requests and bug reports you know customers are waiting on.
Keep an Unreleased section
The keepachangelog convention of an Unreleased section — upcoming changes recorded before they ship — does two jobs: the changelog stays current between releases, and writing the entry happens while the change is fresh, not three weeks later from memory.
Match cadence to your ship rate, then keep it
If you deploy continuously, publish weekly; if you ship monthly releases, publish monthly. What kills changelogs is aspiring to a cadence the team can't sustain. A short entry every week beats a long one every quarter, and a visible rhythm is itself a signal — prospects and users read gaps as product stagnation. Linear's fixed weekly rhythm is the canonical version; we broke it down in release notes examples worth stealing from.
Publish it public and indexable, then distribute it anyway
A changelog behind a login helps nobody evaluating you, and openchangelog's overview makes the broader point: publish where users can actually find it. But findable isn't the same as found — nobody visits a changelog page unprompted. Pair the page with delivery: an in-app widget, an email digest, a post in your community Slack or Discord.
Automate the assembly, not the judgment
The gruntwork — collecting merged PRs, drafting categorized entries — automates well; the full pipeline is in how to automate release notes with AI. Keep a human on what to include and how it's phrased.
One assembly step deserves special mention because no changelog tool covers it: knowing which entries close out specific customers' requests. We build Modem for that piece — it matches merged PRs back to the customers who asked in Slack, support tickets, or email, and drafts the changelog entry along with follow-ups to the requesters. The matching works because Modem keeps a context graph underneath — requesters linked to topics across Slack, tickets, and email — so "whose request does this entry close" is a query, not a memory exercise. That's relevant if identifiable customers ask you for things; a public open-source changelog with anonymous users doesn't need it.
The smallest version this week
Create the page with the New / Improved / Fixed skeleton — copy it from our release notes template — and write this week's entry from what actually merged, bugs named honestly. Put a recurring 20-minute slot on Friday for the next one. Cadence first; widgets, automation, and polish only once four consecutive entries exist.
