Guide
Changelog best practices for a product people trust
Updated 2026-11-02 · 6 min read
Short answerA good changelog is dated, newest first, written in plain words, easy to scan by type, and updated every time you ship. Make it public, give it a feed and an email option, search and link every entry, and say plainly when something breaks.
Why keep a public changelog at all#
A changelog shows the product is alive. For customers it answers "is this still being worked on?" and "did the thing I asked for ship?" For prospects it is evidence. It also cuts support: when something changes, the explanation already exists, with a link.
Eight practices#
1. Publish every time you ship something a user can notice#
Cadence matters more than size. Weekly small entries beat a quarterly essay. If nothing user-visible shipped, publish nothing.
2. Newest first, with real dates#
Readers arrive to find what is new. Put the latest at the top and show the date on each entry. Version numbers are optional; dates are not.
3. Structure each entry the same way#
A short title, one sentence of context, then grouped lists: New, Improved, Fixed, Breaking. A consistent shape lets people scan without reading.
4. Write for the user, not the repository#
Describe outcomes. "Pages load about three times faster on large boards" is an outcome. "Memoised the selector" is not.
5. Be honest about breaking changes#
Put them at the top, say what breaks, who is affected, the date, and the step to fix it. Trust is built in exactly these entries.
6. Make it easy to follow#
Offer an RSS or JSON feed and email, and let people follow only the types of change they want. Give every entry and heading its own link so it can be shared and cited.
7. Make it searchable and filterable#
Once you have fifty entries, a search box and type filters stop being optional.
8. Close the loop#
When a release delivers something customers asked for, tell them. A changelog that doubles as a "you asked, it shipped" message is the one people keep reading.
Pitfalls#
- A changelog that is only ever a link in the footer. Link to it from the product, with a What's New indicator.
- Silent edits. If you correct an entry, say so.
- Marketing voice. Hype reads as noise.
- Skipping the bad news.
Examples to learn from#
Read a few public changelogs of products you use and note what you actually read. You can also see Shipnoted's own changelog, which is a normal Shipnoted page.
Tools#
You can keep a changelog in a Markdown file in your repository, or use a tool. If you want the page themed to your product, a What's New widget in your app, feeds, email and a feedback board connected to it, see Shipnoted's changelog.
Questions and answers
- How often should I update my changelog?
- Each time you ship something users can notice. A small entry every week or two works better than a large one every quarter.
- Should a changelog be public?
- Usually yes, for customer-facing software. It builds trust and reduces support questions. Internal-only changes can stay in a private log.
- What is the best format for a changelog?
- Newest first, a date on each entry, and entries grouped as New, Improved, Fixed and Breaking. Markdown is the simplest way to write them.
- Do I need version numbers in a changelog?
- Not for most web products. Dates are enough. Use version numbers when users install software and need to know which version they have.
- Should a changelog have an RSS feed?
- Yes. A feed and an email option let people follow updates without checking the page.