Keep a Changelog Format Explained: The 2026 SaaS Adaptation Guide

If you've opened the CHANGELOG.md of any serious open-source project in the last ten years, you've seen the same structure: a reverse-chronological list with sections called Added, Changed, Deprecated, Removed, Fixed, and Security. That structure has a name — Keep a Changelog — and since 2014 it has quietly become the most widely adopted changelog format on the planet.

This guide is for SaaS teams who want to keep the developer credibility that Keep a Changelog delivers while also producing release notes their non-technical users actually read. We'll cover what the format specifies, why it won, how to adapt its six categories for a B2B SaaS audience, and how to automate the whole pipeline from conventional commits to customer-facing communication.

What is Keep a Changelog?

Keep a Changelog is a specification — a short, opinionated document maintained at keepachangelog.com — that defines how a project should structure its CHANGELOG.md file. Version 1.0.0 was published in 2017 by Olivier Lacan, refining work that had been circulating since 2014.

The spec boils down to seven principles:

1. Changelogs are for humans, not machines.
2. Every version gets its own section.
3. Entries are grouped by change type.
4. Versions are linkable and dated.
5. The latest version comes first.
6. Entries reference the commit or PR when useful.
7. Semantic Versioning is the default versioning scheme.

That's it. No framework, no tool, no vendor lock-in. A plain-text CHANGELOG.md that any developer in the world recognizes on sight.

The six official categories

Keep a Changelog defines exactly six sections per version:

• Added — new features that did not exist before.
• Changed — changes in existing functionality.
• Deprecated — features that are marked for removal in a future release.
• Removed — features that are gone.
• Fixed — bug fixes.
• Security — vulnerabilities resolved.

The discipline of classifying every change into one of these six buckets is what gives Keep a Changelog its clarity. A new API endpoint is Added. Raising a rate limit is Changed. Removing a flag that was deprecated two releases ago is Removed. Patching CVE-2024-xxxxx is Security.

There is no "Other". There is no "Misc". If a change does not fit one of the six categories, it usually means the change is not customer-facing and does not belong in the changelog.

Before and after: the same release, two formats

Here's a made-up release written without any structure:

## v2.4.0

- dark mode
- dashboard loads faster now
- fixed a bug where invoices were duplicated
- api key rotation endpoint
- the old /v1/customers endpoint is going away next quarter

And the same release following Keep a Changelog:

## [2.4.0] — 2026-03-14

### Added
- Dark mode across every dashboard page, system-preference aware.
- `POST /v2/keys/rotate` endpoint for programmatic API key rotation.

### Changed
- Dashboard initial load is ~40% faster on accounts with 10k+ customers.

### Deprecated
- `/v1/customers` — scheduled for removal on 2026-07-01. Migrate to `/v2/customers`.

### Fixed
- Resolved a race where Stripe webhooks could create duplicate invoices.

The second version is not just prettier. It is searchable, scannable, and parseable by machines (RSS feeds, changelog aggregators, security scanners). It is also, frankly, how serious engineering teams are expected to communicate.

Adapting Keep a Changelog for a B2B SaaS audience

Pure Keep a Changelog is developer-facing. If your users are product managers, marketers, or founders rather than engineers, the raw six-category structure reads too dry. Fortunately, adaptation is simple — preserve the structure, soften the language.

Here is a pattern that works for SaaS products:

Keep the categories, translate the labels

| Keep a Changelog | SaaS-friendly label | |---|---| | Added | New | | Changed | Improved | | Deprecated | Coming soon removal | | Removed | Retired | | Fixed | Fixed | | Security | Security update |

The underlying discipline is identical. The words are warmer.

Lead every entry with user value

Instead of "Added: POST /v2/keys/rotate", write "Rotate API keys without downtime. The new endpoint lets you issue a fresh key, keep the old one valid for 24 hours, then revoke." Same change, lens flipped from engineering output to customer benefit.

Use Keep a Changelog as the source, publish derivatives

Maintain your CHANGELOG.md per the spec. Then automatically derive:

• A public changelog page (the warm, editorial version — see our product changelog guide)
• Email digests (the weekly summary)
• In-app announcements (the "one thing you should know this week")
• Release notes for developers (the exact Keep a Changelog entry, unedited)

The source file is the single source of truth. Everything downstream is a rendering of it.

Semantic Versioning + Conventional Commits = the full pipeline

Keep a Changelog works best when paired with two other conventions:

Semantic Versioning (semver) — the MAJOR.MINOR.PATCH scheme where:

• A MAJOR bump signals a breaking change (goes in Removed or Changed with migration notes).
• A MINOR bump signals new functionality (goes in Added).
• A PATCH bump signals bug fixes (goes in Fixed).

Conventional Commits — a commit message format that tags every commit with a type:

• feat: → maps to Added
• fix: → maps to Fixed
• chore!: or feat!: → maps to Changed (breaking)
• refactor:, test:, docs: → usually don't appear in the changelog

When you combine all three — Keep a Changelog for structure, SemVer for version numbers, Conventional Commits for source signals — you get a pipeline where any engineer can infer the next version number and the right changelog section from a diff log alone. No meetings. No ambiguity. No "did anyone write the release notes yet?" panic on Friday afternoon.

Automating the pipeline with ReleaseGlow

Doing this by hand scales to about 20 releases before someone drops the ball. Tools like ReleaseGlow exist to automate the transformation:

1. Connect your GitHub repository (OAuth, read-only, commit messages only).
2. On every push to main or every merged PR into main, the tool groups commits by version, detects Conventional Commits prefixes, and drafts a Keep-a-Changelog-compliant entry.
3. An AI rewrite pass translates engineering-speak into user-friendly English while preserving the six-category structure.
4. You review, edit if needed, hit Publish.
5. The entry appears in your CHANGELOG.md, on your hosted changelog page, in next week's email digest, and in the in-app widget — all from one click.

The output is still valid Keep a Changelog Markdown, so developers who prefer the raw file see exactly what they expect. Non-technical users get the polished version. See how AI changelog generators work for the deeper technical write-up.

Common mistakes when adopting Keep a Changelog

• Inventing new categories. "Polish", "Miscellaneous", "Internal" — they all drift toward "Other" and defeat the point. Stick to the six.
• Writing for engineers when your audience is customers. The category stays the same, the wording changes.
• Skipping the date. Every version needs an ISO-formatted date. ## [2.4.0] — 2026-03-14 is correct. ## v2.4.0 alone is incomplete.
• Not linking versions. The spec reserves ## [Unreleased] at the top for in-progress work. Every published version should link to its diff ([2.4.0]: https://github.com/you/repo/compare/v2.3.0...v2.4.0).
• Forgetting Security. If you fix a vulnerability, Security is its own section and the entry should link to a CVE or advisory when public.

Why Keep a Changelog won

Other formats existed. GitHub releases, Atlassian's release notes conventions, internal templates at various companies. Keep a Changelog won because it got three things right:

1. It's a specification, not a tool. No vendor dependency. Works in any repo, in any language, forever.
2. It's opinionated enough to be useful. Six categories, strict ordering, mandatory dates. Zero ambiguity.
3. It respects developers. The spec itself is 900 words. Reading it costs you two minutes. Applying it costs you nothing ongoing once it's wired.

Every changelog aggregator, every RSS feed, every AI release-notes generator now speaks Keep a Changelog natively. Adopting it means your release communication immediately plugs into the rest of the developer ecosystem.

Ship your first Keep-a-Changelog entry this week

If your product has a CHANGELOG.md, audit it tonight against the spec and the six categories. If it doesn't, create one with ## [Unreleased] at the top and a single link to the keepachangelog.com spec in the header. On your next release, write one entry per the format.

You'll gain developer credibility on day one. And if you pair the file with an automated pipeline that also publishes a warm, customer-facing version, you'll never have to choose between engineering discipline and marketing polish again.