How to Write a Changelog People Actually Read (2026)

Why a Public Changelog Helps

A changelog is a dated list of what changed in your product. Keep a Changelog, a set of conventions for these files, calls it "a curated, chronologically ordered list of notable changes for each version of a project." The word that matters is curated: it's written for people, not generated from your commits.

For a small product, a public changelog does three jobs:

• It shows the product is alive. A visitor who wonders whether a tool is still maintained looks for signs of recent work. A changelog with an entry from last week answers that faster than any claim on your homepage.
• It gives people something new to read. Users see what they've been missing, people who tried it once see the thing they asked for, and search engines find a page that keeps growing, with entries that name the features people search for.
• It gives you a reason to post. "We shipped this" with a screenshot is a better update than "still building!", and a changelog turns every release into one.

Be realistic about search: don't count on a changelog page to rank by itself. Its value is steady, specific text about the product, with links to the feature pages and docs where the detail lives.

What to Include and What to Leave Out

The test for every line: would a user notice this change, or need to act on it? If yes, it goes in.

Include:

• New features and new integrations.
• Improvements people will notice: faster exports, a clearer settings page, a new keyboard shortcut.
• Fixes for bugs users saw, especially ones they reported.
• Anything removed, renamed or about to go away, and any change that breaks how someone works today.
• Changes to pricing, plans or limits.
• Security fixes, in general terms that won't help an attacker.

Keep a Changelog is firm about the uncomfortable items: "If you do nothing else, list deprecations, removals, and any breaking changes in your changelog." Users take a removed feature much better when they hear it from you first.

Leave out:

• Refactors, test changes, build tweaks and dependency bumps, unless they change something users see or, for a library or self-hosted app, something they must update.
• Commit hashes, ticket numbers and internal code names.
• Features behind a flag that most users can't see yet.
• Filler. "Various improvements" tells nobody anything.

Don't paste your commit log either. In Keep a Changelog's words, "Using commit log diffs as changelogs is a bad idea: they're full of noise."

How often? Publish when there's something worth reading, ideally on a steady rhythm such as every week or two, and batch small fixes into one entry. A changelog whose last entry is a year old says the opposite of what you want, so keep it going or take the link off your homepage.

Write Entries for Users, Not Developers

This is where most changelogs fall short. The entry is accurate, but it's written for the person who made the change, not the person who'll use it.

• Lead with the benefit. Say what someone can do now, then how. "You can now export any report as a PDF" beats "Added PDF export endpoint".
• Use plain words. Name screens and buttons the way they appear in the product. Skip internal terms and acronyms.
• Say where to find it. "In Settings, under Billing" saves a support email.
• Show it. One screenshot or a short GIF for anything visual, cropped to the part that changed.
• Describe fixes as the problem users saw. "Invoices no longer show the wrong currency for some customers", not "Fix locale bug in formatter".
• Credit people. If a user asked for the feature, thank them by name, with their permission.

A quick before and after:

Keep each entry short. A headline, a sentence or two and a screenshot covers most changes. Link to your docs for the detail.

A Structure That Works

Keep a Changelog's guiding principles make a good base, whether or not you use its file format: changelogs are for humans, the latest version comes first, every release shows its date, the same types of changes are grouped, and versions and sections are linkable.

For a changelog page on your site, that becomes:

1. A date on every entry, newest first. Keep a Changelog recommends the ISO 8601 format, YYYY-MM-DD. Avoid 11/12/2026, which means different days in different countries.
2. A headline that names the biggest change, written as what users can do now.
3. A short summary and a screenshot for that headline change.
4. Smaller items, grouped. Keep a Changelog uses six types: Added, Changed, Deprecated, Removed, Fixed and Security. For a product page, New, Improved and Fixed often cover it, plus a clear note whenever something is removed.
5. A link for every entry, either its own page or an anchor, so you can point a user or a post straight at it.

Here's an entry to copy and fill in:

Delete the lines you don't need.

Version Numbers and Conventions

Whether you need version numbers depends on what you ship.

If people install your product or build on it, such as a library, an API, a command-line tool, a browser extension, a desktop or mobile app, or self-hosted software, use version numbers. People need to know what they're running and whether an update will break something. Semantic Versioning 2.0.0 is a well-known scheme for this. Given a version number MAJOR.MINOR.PATCH, you increment the:

• MAJOR version when you make incompatible API changes,
• MINOR version when you add functionality in a backward compatible manner,
• PATCH version when you make backward compatible bug fixes.

From the spec and its FAQ: version 0.y.z is for initial development, when "Anything MAY change at any time"; the FAQ suggests starting at 0.1.0 and bumping the minor version for each release. It also says that if your software is being used in production, it should probably already be 1.0.0. And "v1.2.3" isn't a semantic version: the "v" is a common prefix in Git tags, and the version itself is 1.2.3.

If it's a hosted web app, where everyone is always on the latest version, dates usually do the job and version numbers add little. Use them if your API is versioned or customers ask for them.

The Keep a Changelog format

For a changelog that lives in your repository, Keep a Changelog 1.1.0 is a simple format to follow. It suggests a file called CHANGELOG.md, an Unreleased section at the top to collect changes before the next release, the six change types above, and a [YANKED] tag for releases pulled because of a serious bug or security issue. It also asks you to say whether you follow Semantic Versioning.

Where to Publish It

Put the changelog where each kind of reader will see it:

• A changelog page on your site, such as /changelog, linked from your footer and docs. This is the one search engines and new visitors find. Offer an RSS feed or email updates for people who want them.
• Inside the product, for changes that affect what users do: a small "What's new" note or dot that links to the entry. Save pop-ups for big changes; a pop-up for every fix teaches people to close it without reading.
• App store release notes. Apple's App Store Connect has a What's New in This Version field of up to 4,000 characters, required for every version after the first. Apple's App Review Guidelines (2.3.12) say apps must clearly describe new features and product changes there; simple bug fixes, security updates and performance improvements may use a generic description. Google Play allows up to 500 Unicode characters of release notes per language, and says not to use them for promotion or to ask users to take an action.
• GitHub releases, for open-source projects and anything people install from a repository. GitHub can generate release notes that list merged pull requests, the release's contributors and a link to the full changelog, and a .github/release.yml file groups them by label. Treat the generated list as a draft and add a few lines at the top, written for users, about what matters in this release. Keep a Changelog points out that GitHub Releases make a changelog that can only be shown within GitHub, so keep a CHANGELOG.md or a page on your site as well. Our guide to launching an open-source project covers tagging your first release.

Write the full entry once, on your changelog page, then cut it down for each place. One source keeps the versions from drifting apart.

Turning Entries Into Posts

A changelog entry is most of a post already: the change, the benefit, a screenshot and a link. What a post adds is the reason someone should care today.

1. Pick the entries worth posting. Not every fix earns a post. A feature users asked for, a change that saves real time, or a fix for a problem many people hit does.
2. Lead with the problem, not the feature. "Exporting a report used to take three clicks and an email. Now it's one button." Then the screenshot or a short clip.
3. Credit the person who asked, if they're happy to be named, and tag them where the platform allows it.
4. Link to the entry, not your homepage, with UTM tags such as utm_source=x and utm_content=changelog, so you can see which posts send visits. The UTM builder makes them.
5. Adapt it for each platform. On X, a short post with the clip; the X thread builder helps when there's a story to tell. On LinkedIn, lead with the problem and who it helps; the LinkedIn post formatter checks your opening lines. Our guides to announcing on X and on LinkedIn cover the rest.

Once a month, a roundup post ("Everything we shipped in October") catches people who missed the single updates, and makes a good email to users.

Over a few months, the changelog also becomes the case for launching again. Once a returning visitor would see a clearly different product, our guide to what to do after launch day covers when and how to relaunch. If you haven't launched yet, submit your product to Hauntboard; every launch keeps a permanent page that links to your site.