Keep a Changelog: 9 Rules for Writing Changelogs Developers and Users Actually Read

The problem changelogs are supposed to solve

Every software project changes over time. Users need to know what changed. Developers need a record of what shipped and when. Product managers need to communicate progress to stakeholders and customers.

Without a structured changelog, this information scatters across git logs, Slack threads, Jira tickets, and the memories of whoever happened to be in the standup that day. Six months later, nobody can tell you what shipped in Q1 without excavating a dozen tools.

A changelog solves this by being the single, human-readable record of notable changes. But only if it is written well. A bad changelog — a dump of commit messages, a wall of jargon, a marketing press release disguised as release notes — is worse than no changelog at all. It teaches users to ignore it.

What is Keep a Changelog?

Keep a Changelog (keepachangelog.com) is an open-source project created by Olivier Lacan that defines a simple, consistent format for changelogs. It has become the de facto standard in the open-source world and increasingly in SaaS products.

The core philosophy is captured in one sentence from the project: “Don’t let your friends dump git logs into changelogs.”

Keep a Changelog defines six entry types — Added, Changed, Deprecated, Removed, Fixed, and Security — and a set of guiding principles about how changelogs should be structured. It pairs naturally with Semantic Versioning but works equally well with date-based releases common in SaaS.

The principles below build on this standard and extend it with practical guidance for teams shipping SaaS products, APIs, and developer tools.

Rule 1: Write for humans, not machines

This is the foundational rule from Keep a Changelog, and the one most teams violate. A changelog is for people — the customers, developers, and product managers who need to understand what changed without reading the source code.

The test is simple: could a non-technical stakeholder read this entry and understand what changed? If not, rewrite it.

The first version is a commit message copy-pasted into a changelog. The second is a changelog entry. Same change. Different audience.

Rule 2: Use the six standard categories

Keep a Changelog defines six entry types, and they cover every kind of change you will ever ship. Using them consistently gives your changelog a scannable structure that users learn to navigate.

Resist the urge to invent your own categories. “Improvements,” “Tweaks,” “Misc” — these mean nothing to a reader scanning for relevant changes. The six standard types are specific enough to be useful and broad enough to cover everything.

Rule 3: Put the newest changes first

Reverse chronological order. Always. The most recent release goes at the top. This is how every user expects a changelog to work: they open it to see what changed recently, not to read a history book from page one.

Keep a Changelog mandates this, and it is the right call. If your changelog requires scrolling past two years of entries to find last week’s update, the structure is broken.

For SaaS products, date your entries clearly. Users do not track your internal version numbers. “March 7, 2026” is universally understood. “v4.2.1-beta.3” is not.

Rule 4: One entry per notable change

The single most common changelog anti-pattern is the catch-all entry:

“Various improvements” tells the user nothing. It is the changelog equivalent of shrugging. A user who reported the CSV bug cannot tell whether it was fixed. A user affected by the Firefox issue has no way to know it was addressed.

List changes individually. If you shipped 15 things and only 6 are user-facing, list those 6. Add a single line at the bottom for the rest: “Plus several internal stability improvements.” That is acceptable. Replacing everything with that line is not.

Rule 5: Never dump your git log

Keep a Changelog was born from this frustration. A git log is a record of every commit — merge commits, typo fixes, dependency bumps, work-in-progress checkpoints. Dumping this into a changelog is not transparency. It is noise.

Six commits. Two changelog entries. That is the curation a changelog demands. The lint fixes, the merge commits, the typo corrections — those are development artifacts, not user-facing changes.

Rule 6: Show the user impact, not the implementation

This is where the gap between developer culture and user communication becomes most visible. Engineers naturally describe changes in terms of what they built. Users need to understand changes in terms of what shifted in their experience.

Both describe the same work. The first tells developers what you did. The second tells users what they gained. For a product changelog, always write the second version. If you also serve a developer audience that cares about the internals, link to a technical blog post from the changelog entry.

Rule 7: Maintain an Unreleased section

This is one of Keep a Changelog’s most underused recommendations. Keep an “Unreleased” section at the top of your changelog where you accumulate changes as they are merged but before they ship to users.

The Unreleased section solves two problems:

• It eliminates the end-of-cycle scramble. Instead of reconstructing what shipped from memory and git history, you already have a running list ready for review and publication.
• It makes your changelog part of the workflow. When adding to Unreleased is part of the PR review checklist, the changelog stays current without dedicated “changelog writing” sessions that nobody wants to attend.

For SaaS teams, this translates to keeping a draft entry always in progress. When your release is ready, you review the draft, polish it, and publish. Five minutes instead of an hour.

Tools like Changelog.dev automate this pattern. Connect your GitHub repo and it maintains a running draft from your commits and pull request descriptions. When you are ready to publish, the draft is already there — you review, edit for tone, and ship. The Unreleased-to-published workflow without the manual bookkeeping.

Rule 8: Be honest about removals and deprecations

This is the rule that separates changelogs that build trust from changelogs that erode it. When you remove a feature or deprecate an endpoint, users need to know before they discover it by hitting an error.

Three principles for communicating removals:

1. Announce deprecation before removal. Give users at least one release cycle of warning. “Deprecated: The /v1/export endpoint will be removed in April 2026. Use /v2/export instead.”
2. Explain the migration path. Do not just announce the removal. Tell users what to do instead. Link to documentation if available.
3. Never hide breaking changes. Burying a breaking change in a “miscellaneous” section, or worse, not mentioning it at all, guarantees angry support tickets and social media complaints. The short-term discomfort of announcing a removal is nothing compared to the long-term damage of users discovering it by accident.

Rule 9: Ship on a consistent cadence

A changelog that was last updated seven months ago sends one of two signals: the product is abandoned, or the team does not care about communicating with users. Neither is the signal you want.

The right cadence depends on your shipping pace:

• Shipping daily or weekly: Publish a weekly or bi-weekly changelog roundup. Batch small changes to avoid notification fatigue.
• Shipping on sprints: Publish at the end of each sprint. Two-week cadence works well for most teams.
• Shipping monthly: Monthly changelogs are the minimum viable cadence for any active product. Below this, users start to wonder if anyone is working on it.

The golden rule: never go more than six weeks without a changelog update if the product is under active development. If you genuinely shipped nothing user-facing in six weeks, that is a product problem, not a changelog problem.

Consistency matters more than volume. Three entries every two weeks builds more trust than a massive changelog dump every quarter. Users calibrate expectations based on your rhythm. Give them a rhythm they can rely on.

Putting it all together: a complete changelog entry

Here is what a monthly changelog entry looks like when all nine rules are applied:

Scannable. Categorized. Dated. Written for the person using the product. Every entry answers the question: what does this mean for me?

How to start if you have no changelog

If your product does not have a changelog yet, do not try to retroactively document everything. Start from today:

1. Create the page. A /changelog route on your site, a CHANGELOG.md in your repo, or a dedicated tool — whatever gets it live fastest.
2. Write one entry. Describe the most recent notable change you shipped. Use the Keep a Changelog format. Date it.
3. Set a cadence. Put a recurring calendar event for changelog review. Monthly is fine to start.
4. Make it part of your workflow. Add “update changelog” to your PR template or definition of done. The best time to write a changelog entry is immediately after shipping, when context is fresh.

That is the entire cold start. One page, one entry, one recurring reminder. Everything else is refinement over time.

If you want to skip the manual setup, Changelog.dev gives you a hosted changelog page, an embeddable widget for your app, and AI-drafted entries from your GitHub commits. Free tier, no credit card. You can go from zero to a published changelog in under five minutes.

The compound effect of a good changelog

A changelog is a trust ledger. Every entry is a deposit. Over months and years, the balance compounds in ways that are difficult to replicate with any other marketing or communication channel:

• Prospects evaluate your changelog before buying. In B2B SaaS, a two-year changelog history is proof that the product is actively maintained. It cannot be faked.
• Support tickets decrease. Users who check the changelog before filing a ticket often find their answer. “Was this bug fixed?” “Did this feature ship?” The changelog answers both.
• Churn decreases. Users who see regular improvements are less likely to leave. The changelog reminds them that the product is getting better, even if the specific changes do not affect them directly.
• Feature requests improve. Users who read changelogs understand where the product is heading. Their requests become more aligned with your roadmap.
• SEO compounds. Every changelog entry is indexed content that targets long-tail keywords related to your product and the problems it solves.

None of this requires a large team, a dedicated technical writer, or expensive tooling. It requires a decision: treat the changelog as a first-class product artifact, not an afterthought. Follow the Keep a Changelog standard. Write for humans. Ship consistently.

The best changelog you will ever write is the next one. Start today.