Pick where customers will read it, then record each change as a short dated entry with a plain-language title and a label such as new, improved or fixed. Publish it on a public page your product links to, add an in-app notice for important changes, and make writing the entry part of every release.
A changelog is the cheapest trust signal a software product has. It tells customers the product is alive, that the bug they reported got fixed, and that the feature they asked for shipped. Yet many changelogs read like commit logs, or stop being updated after the first month. Both problems come from the same place: nobody decided who the changelog was for.
Who's reading it decides how you write it
There are two quite different readers, and one page rarely serves both well.
- Developers reading release notes want versions, technical detail and a link to the full list of changes.
- Customers want to know what's new, what's better and what got fixed, in plain words, with a reason to care.
If your product has both audiences, keep technical release notes alongside your code and a separate customer-facing changelog. The audience decides how technical the wording should be, so make that call first.
What a good entry looks like
Consistent entries are quick to scan. Each one needs four parts:
- A date, so readers can see how fresh each change is.
- A short, plain title that a customer would understand.
- One or two sentences on what changed and why it helps them.
- A label such as new, improved or fixed.
A title like 'Refactor export service' means something to your team and nothing to a customer. 'Exports now finish faster on large files' tells the reader what they get. The second version is the one that belongs in a customer changelog.
Seven steps to a changelog that stays current
- Decide who it's for. Developers reading release notes, or customers who want to know what's new. If developers are your audience, GitHub Releases keeps notes next to the code.
- Choose its home. A public page on your own domain, a page in your docs or a release feed in your repository. Headway gives you a hosted changelog page, and AnnounceKit hosts a branded one on your own domain. Customers must be able to find it without asking.
- Write each entry to the same pattern. Date, plain title, a sentence or two and a label. LaunchNotes has AI drafting inside its editor if a first draft helps.
- Link it everywhere customers look. Your app, site footer and help centre, plus an in-app notice for changes customers will notice. Beamer handles in-app and push notifications. A changelog nobody sees doesn't build trust.
- Send the big updates out. Use the channels customers already use, such as email, Slack or RSS. AnnounceKit sends one update to all of them. Not everyone checks the page.
- Close the loop on requests. Connect entries to the requests that triggered them and tell the people who asked. Frill ties announcements to the ideas customers voted on.
- Make it a release checklist item. No tool does this for you: the entry ships with the change, or the changelog goes stale.
Why generated release notes need a rewrite
If your code lives on GitHub, it's tempting to press the button that writes release notes for you and paste the result into your customer changelog. Treat that output as a draft.
GitHub's own documentation says automatically generated release notes list the merged pull requests, the contributors and a link to the full changelog. It also tells you to check that the output includes all and only the information you want. You can use labels to group items into categories, and to exclude ones you don't want listed.
The problem for a customer audience is the pull request titles. They're written by developers for developers, so they describe the code change, not what the customer gets. Before you publish, rewrite each item in plain language, cut anything internal, and use labels to keep housekeeping work out of the notes entirely. The generated list saves you remembering what shipped. The rewrite is what makes it readable.
Six tools for publishing product updates
Headway
A changelog tool that gives you a public changelog page and an in-product widget of the latest changes, with entries labelled such as New, Fix and Bug.
AnnounceKit
Hosts a branded changelog on your own domain, with in-app widgets and updates sent through in-app, email, Slack and RSS from a single post.
Beamer
A product update and notification platform for announcing updates, bug fixes and news, with push notifications that reach users who aren't logged in, plus segmentation and personalisation.
LaunchNotes
Release notes, a changelog, a roadmap and a feedback widget in one product, with AI drafting in its editor.
Want AI doing the heavy lifting in your marketing?
I build the systems that handle the boring 80 percent, so you get your week back. Done properly, with the human kept in.
Frill
Combines ideas, a roadmap and announcements, so you can tell customers about updates from one place embedded in your product, linked to the feature requests they voted on.
GitHub Releases
Release notes built into GitHub. It can generate notes from merged pull requests and contributors, with a configurable categories file to group and exclude items by label.
There's a longer comparison of changelog tools and what each one includes. If you're also choosing where the work gets tracked before it ships, these issue trackers for product teams are worth a look, and interactive product demos can show a big new feature better than a paragraph can.
The verdict: make it part of shipping
The tool matters far less than the habit. Pick one reader, one home and one entry pattern, then make writing the entry a step in every release rather than a job someone does when they remember. A short, plain, current changelog does more for trust than a beautiful one that stopped three releases ago.
Want your tool on this list? Featured spots and reviews here are paid partnerships. Here's how to partner with me.
Frequently asked questions
What is a changelog?
It's a dated record of changes to a product, written so customers can keep up with what's new, improved and fixed.
What should a changelog entry include?
A date, a plain title, what changed and a label. Headway's example entries use labels such as New and Fix.
Can I create a changelog for free?
If your code is on GitHub, its release notes generator is built in. For the hosted tools here, no free plan is stated on their pages.
How is a changelog different from release notes?
Release notes usually describe one release, while a changelog is the running history. LaunchNotes offers both release notes and a changelog.
How do I tell customers about updates?
Use an in-app widget or notification, and email, Slack or RSS for bigger changes. Beamer lists push and in-app notifications for this.
