A changelog is a curated, chronologically ordered list of the notable changes in each version of a product. The most widely adopted format groups every entry under six headings, Added, Changed, Deprecated, Removed, Fixed and Security, lists the newest version first, and dates each release in ISO 8601 format.
Key takeaways. There is no official standard, only one convention that most of the industry follows, and following it is worth more than inventing your own. The six categories exist so a reader can find breaking changes in three seconds, which is the only job a changelog really has. Write entries for the person upgrading, not the person who wrote the commit. Public changelogs and developer CHANGELOG.md files are the same idea in two registers: one is prose with screenshots, the other is markdown under version control. And the hardest part is not the format, it is publishing on a rhythm that people can rely on.
What does a good changelog look like?
A good changelog is legible to someone who did not write the code. That single test eliminates most of what teams publish. A dumped git log fails it. A list of ticket numbers fails it. “Bug fixes and performance improvements” fails it hardest of all, because it consumes the reader’s attention and returns nothing.
The reference document for this is Keep a Changelog, a convention created and maintained by Olivier Lacan, now at version 1.1.0 and translated into 28 languages. Its guiding principles are short enough to quote in full:
- Changelogs are for humans, not machines.
- There should be an entry for every single version.
- The same types of changes should be grouped.
- Versions and sections should be linkable.
- The latest version comes first.
- The release date of each version is displayed.
- Mention whether you follow Semantic Versioning.
The document is equally direct about what makes a changelog bad. It calls out commit log diffs as noise, ignoring deprecations as the failure that breaks upgrades, ambiguous regional date formats, and inconsistency, which it describes as almost as dangerous as having no changelog at all, because readers start treating the file as a source of truth and it quietly is not one.
The key point is that a changelog is a contract about attention. Your users agree to read it if you agree not to waste their time.
What is the standard changelog format?
Here is the honest answer, and it is the one the convention itself gives: there is no official standard. Keep a Changelog’s own FAQ says so plainly, noting that the GNU changelog style guide and the GNU NEWS file guideline are both inadequate, and describing itself as an attempt at a better convention gathered from open source practice rather than a specification handed down by a standards body.
What exists instead is a convention that has won by adoption. It looks like this.
| Category | Use it for | Example entry |
|---|---|---|
| Added | New features | Added SSO support for Okta and OneLogin. |
| Changed | Changes to existing functionality | Changed the default export format from CSV to XLSX. |
| Deprecated | Features that will be removed soon | Deprecated the v1 webhook payload. It will be removed in 3.0.0. |
| Removed | Features that are now gone | Removed the legacy dashboard and its routes. |
| Fixed | Bug fixes | Fixed a crash when a project name contained an emoji. |
| Security | Vulnerabilities | Security patched a path traversal issue in file uploads. |
Four more rules carry most of the value:
- Newest first. The top of the file is the most recent release. Nobody scrolls to find out what just shipped.
- Date every version in ISO 8601. Write 2026-08-07, not 08/07/2026. The ISO ordering runs largest unit to smallest and cannot be misread by a reader in another country.
- Pair it with Semantic Versioning. Major for breaking changes, minor for backwards compatible additions, patch for fixes. The version number then tells the reader how carefully to read the entry.
- Keep an Unreleased section at the top. It is where changes accumulate between releases, so writing the changelog stops being a release day scramble and becomes a line added with each merge. This is the single habit that keeps changelogs alive.
One more convention worth knowing: a release pulled because of a serious bug or security issue is marked with a loud [YANKED] tag on its heading, so nobody installs it by accident.
How do you write a changelog entry?
Start from the file. Copy this, save it as CHANGELOG.md in your repository root, and add lines to Unreleased as you merge.
# Changelog
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.
## [Unreleased]
### Added
## [2.1.0] - 2026-08-07
### Added
- Bulk import for CSV files up to 50 MB.
- Keyboard shortcut for the command palette.
### Changed
- Search now matches on tags as well as titles.
### Fixed
- Fixed timezone drift on scheduled exports.
## [2.0.1] - 2026-07-22
### Security
- Patched an authorisation gap on shared board links.
## [2.0.0] - 2026-07-15
### Removed
- Removed the v1 API. See the migration guide.
### Deprecated
- The legacy webhook payload will be removed in 3.0.0.
For the entry itself, a three part formula holds up in almost every case: verb, object, consequence.
- Start with the change, in past tense. Added, Changed, Fixed, Removed. The category heading already tells the reader which; the verb keeps each line scannable on its own when it gets quoted out of context.
- Name the thing in the user’s vocabulary. “Bulk import”, not “the ImportBatchProcessor”. If a user cannot search your docs for the noun you used, you used the wrong noun.
- State the consequence when there is one. Breaking changes, migration steps, and anything that changes a default all need a clause explaining what the reader must now do. Everything else can be one line.
A quick before and after. Before: fix(api): update serializer per PR #4412. After: Fixed an error where webhook payloads omitted the project ID on status changes. Same commit, and only one of them answers the question a reader actually has.
If you publish a customer facing version as well as a developer file, write the customer version second and keep it shorter. Most releases deserve one sentence and a screenshot. A few deserve three paragraphs. Very few deserve a blog post.
Changelog versus release notes: what is the difference?
They overlap enough that many teams use the words interchangeably, but the distinction is useful.
| Changelog | Release notes | |
|---|---|---|
| Audience | Users and developers tracking every version | Users deciding whether to care about this release |
| Scope | Every notable change, complete and cumulative | Selected highlights of one release |
| Format | Terse, categorised, one line per change | Narrative, with context, screenshots and links |
| Cadence | Every version, without exception | Per release, sometimes only for significant ones |
| Lives in | CHANGELOG.md or a public feed |
A post, an email, an in-app announcement |
The practical relationship: the changelog is the record, release notes are the announcement. The record must be complete or it is worthless. The announcement must be selective or nobody reads it. We covered the announcement side separately in our guide to improving your release notes, and the case for keeping the record at all in do you already keep a changelog.
8 changelog examples worth studying
These are public pages you can open right now. Each one solves a different problem, which is the point: copy the pattern that matches your audience, not the one that looks best.
| Product | Changelog | What it does well |
|---|---|---|
| GitHub | github.blog/changelog | A reverse chronological feed where every entry has its own permanent URL, so a single change can be linked from a support reply |
| Linear | linear.app/changelog | Editorial presentation, rich visuals per entry, and a house voice that reads like a product person wrote it rather than a release script |
| Vercel | vercel.com/changelog | Dated entries tagged by product area and filterable, which is what you need once you ship more than one thing at a time |
| Stripe | stripe.com/changelog | Versioned API changes with migration notes, the gold standard for anything with a breaking change surface |
| Figma | figma.com/release-notes | Annotated interface visuals, so a change to a tool is shown in the tool rather than described |
| Notion | notion.so/releases | Outcome led language: entries say what you can now do, not what was built |
| Keep a Changelog | the project’s own CHANGELOG.md | The convention applied to itself, including linkable version headings and comparison links between tags |
| Sleekplan | sleekplan.com/changelog | The changelog sits next to the feedback board, so a shipped entry notifies the people who voted for it |
What the good ones share, and it is not design: a permanent URL per entry, a date on everything, consistent categories, and a subscribe path so readers do not have to remember to check. What the bad ones share is a gap of four months followed by an apology post.
That last point is the one worth taking seriously. A changelog is a promise about frequency. If you cannot publish every release, publish a shorter entry rather than none.
Can AI write your changelog?
It can write the draft. It should not decide the contents.
The reliable division of labour in 2026 looks like this. AI reads the merged pull requests, closed issues and commit messages since the last release, groups them into the six categories, drops the internal noise, and produces a draft in your house voice. A human then does three things a model cannot do well: decides what is notable, checks that every breaking change is flagged, and rewrites anything that describes the implementation instead of the outcome.
That middle judgement is the whole game. A model has no way of knowing that a one line config change quietly alters a default for every customer on an old plan, while the 400 line refactor above it changes nothing anyone will notice. Notability is a product decision wearing an engineering costume.
At Sleekplan, Sleek Intelligence drafts changelog entries from shipped work and publishes them to the changelog attached to your feedback board, which means the people who voted for a request are notified when it lands. We wrote up the workflow in more detail, including how to codify your own house style, in how to use AI to write changelog updates.
My honest take: the format was never the hard part. Teams do not have bad changelogs because they picked the wrong headings. They have bad changelogs because writing one is the last task before a release ships and the first task to get cut. AI is genuinely useful here, not because it writes better than you do, but because it removes the excuse.
FAQ
What is the standard changelog format?
There is no official standard, and the most widely used convention says so itself. In practice the industry default is the Keep a Changelog structure: a CHANGELOG.md file, newest version first, each version headed by its number and an ISO 8601 date, with changes grouped under Added, Changed, Deprecated, Removed, Fixed and Security. Pair it with Semantic Versioning so the version number signals how disruptive the release is.
What should a changelog entry include?
One line per change, written in past tense, naming the feature in the words your users use, plus a consequence clause when the reader has to do something. Breaking changes, removals and changed defaults always need that clause. Skip ticket numbers unless your readers can open them, and skip internal refactors that no user can observe.
What is the difference between a changelog and release notes?
A changelog is the complete, cumulative record of every notable change, kept in a terse categorised format. Release notes are a selective announcement of one release, written as narrative with screenshots and links. The changelog must be exhaustive to be trustworthy. Release notes must be selective to be read. Most teams need both, and they should not be the same document.
How often should you publish a changelog?
Every release, without exceptions. The mechanism that makes this sustainable is an Unreleased section at the top of the file: contributors add a line as part of the change itself, so at release time you rename a heading instead of reconstructing history. Teams that write the changelog after the fact are the teams whose changelogs eventually stop.
Should a changelog be public?
For most products, yes. A public changelog reduces support volume, gives sales a place to point when a prospect asks whether you actually ship, and gives your existing users a reason to look at what they are paying for. The exception is a change that reveals unannounced strategy or an unpatched vulnerability window; those get held, not hidden forever.
What should the changelog file be called?
CHANGELOG.md, in the root of the repository. Some projects use HISTORY, NEWS or RELEASES, and all of those work, but they make the file harder to find for anyone arriving from another codebase. The uppercase convention exists so the file sits next to README and CONTRIBUTING where people already look.