Changelog best practices come down to five habits: write the outcome rather than the ticket, link each entry to the requests it resolves, tell the people who asked, label every entry, and publish on a predictable rhythm. A changelog is not release notes. Release notes describe what changed in the software; a changelog tells a specific customer that the thing they complained about is now fixed, and that is the message a customer remembers when deciding whether feedback was worth giving.
Write the outcome, not the ticket
'Refactored the export pipeline' means nothing to a customer. 'CSV exports over 100k rows now finish in seconds instead of timing out' names the pain they reported.
One entry per user-visible outcome. Bundle the eleven commits behind it and never publish an entry a non-technical user cannot parse in one read.
The quickest test is to read the entry as the customer who reported the problem. If they would have to ask 'so does that fix my thing?', rewrite it until the answer is in the first sentence.
| Ticket-style entry | Customer-facing entry |
|---|---|
| Refactored export pipeline | CSV exports of more than 100,000 rows now finish instead of timing out. |
| Null check in date picker | Picking a date while working in another time zone no longer resets the field to today. |
| Added role field to invite modal | When you invite a teammate you can now choose their role, so they no longer join as an admin by default. |
Notify the people who asked
The highest-value moment in a feedback loop is the email that says 'you requested this in November, it shipped today.' It costs almost nothing to send. It is also the message most likely to persuade a customer that posting feedback was worth their time.
This requires your changelog to be linked to the original requests, not written separately in a marketing tool.
Include the people who asked in a different way, too. When duplicates were merged into the request, their authors and voters asked for the same thing and should hear the same news. When the shipped version solves only part of the request, say so in the entry, and leave the original post open for the rest; telling someone their request shipped when it did not is worse than saying nothing.
Read next: How to Close the Customer Feedback Loop
Publish on a rhythm
Weekly or biweekly beats continuous. A predictable cadence trains customers to read it; a firehose trains them to ignore it.
Keep an archive with permalinks. Sales links individual entries into deals, and support links them into tickets.
Break the rhythm only for news that cannot wait: a fix for an outage, a security change customers must act on, or a deadline such as a deprecated feature. In a quiet week, skip the entry rather than padding it with minor tweaks; a thin entry teaches readers that the changelog is not worth opening.
Label every entry
Three labels cover almost everything: New for something customers could not do before, Improved for something that now works better, and Fixed for something that was broken. Readers skim by label. An admin looking for the bug they reported scans the Fixed entries; a prospect checking whether the product is moving reads New.
Add a product-area category once the changelog has enough entries to need filtering, and use the same names your feedback board uses, so a customer who posted under Reporting finds the fix under Reporting. Resist marketing labels such as 'Big news' or 'Exciting update', which tell the reader nothing about whether to keep reading.
Decide who writes it
Entries written by whoever merged the code read like commit messages, and entries written by marketing tend to oversell. What works for most teams is a product manager drafting the entry from the original request, an engineer checking it is accurate, and someone from support reading it before it goes out, because support fields the replies.
Draft the entry when the work is scoped rather than when it ships. Writing the customer-facing sentence early is a useful check on whether the team is building what the customer asked for.
What a good entry looks like
An example, built from the advice above. Title: 'CSV exports no longer time out on large boards.' Label: Fixed. Body: 'Exports of more than 100,000 rows now finish in seconds. Thank you to everyone who voted for this.' Linked requests: the original post and the two duplicates merged into it, so every person who asked is told.
Each part answers a question the customer has: what changed, whether it affects me, and whether anyone listened. Nothing in it names a ticket, a sprint or an internal team, and nothing needs a second read.
Then put the changelog where customers already look: a link in the app's help menu, an in-app widget for the announcements that matter, and an RSS feed for the few who want every entry.
Read next: Changelog page template
What to leave out
A changelog earns attention by being short. These belong somewhere else.
- Internal refactors, dependency upgrades and test changes with no visible effect.
- Ticket numbers, sprint names and team names, which mean nothing outside the company.
- Dates for work that has not shipped. Put intentions on the roadmap, where they can change.
- Every small copy or spacing tweak. Group them into one 'smaller improvements' line, or leave them out.
- Anything a customer would need to read twice. If it needs a diagram, link to a help article.
A pre-publish checklist
Run through this before each entry goes live. It takes a minute.
- The first sentence says what changed and who it affects.
- The entry has one label: New, Improved or Fixed.
- Every request it resolves is linked, including duplicates that were merged in.
- If the request is only partly solved, the entry says so and the post stays open.
- A screenshot or short clip is included where the change is visual.
- Support has read it and knows what customers will ask next.
Measure it
Track opens on the notification, views on the entry, and reactions. When an entry gets plenty of views and few reactions, ask the people who requested it whether the release solved their problem; it may have shipped without the part that mattered to them.
The more useful measure is what customers do afterwards. Compare the people who were told a request shipped with those who were not: do they post or vote again within a month? Watch support volume on the topic of each fix, which should fall after the entry goes out, and ask sales how often they link entries into deals. None of these needs a benchmark; the trend over a few months tells you whether the changelog is doing its job.
Common changelog mistakes
Most changelogs fail slowly, through habits that each look harmless.
- Writing it after the fact from the commit log, so entries describe code rather than outcomes.
- Publishing in bursts after months of silence, which reads as a product that stalled.
- Announcing the same change twice, once as a status update and again as an entry, so customers learn to skim both.
- Keeping the changelog in a separate tool from the requests, so nobody remembers to tell the people who asked.
- Hiding it in a footer link that customers never see.
Publishing a changelog in Looph
In Looph you write an entry in Markdown, give it a type (New, Improved or Fixed) and an optional category, and link the feedback posts it resolves. When you publish, a dialog shows how many posts and people the entry reaches and offers to mark the linked posts Complete, tell everyone following them that it shipped, and comment on each post with a link to the entry. Each person gets one message, by email, in the app and by push, listing everything they asked for in that release. Followers of duplicates merged into a linked post are included, and someone already told that a post shipped is not told again.
Every entry has its own page, and the changelog has a public page with search and filters, an RSS feed, a read-only embed for your own site, and cards in any Slack or Discord channel subscribed to it. You can unpublish an entry after it goes live. An in-app widget and scheduled publishing are coming soon. Publish a changelog entry walks through the steps, and the changelog template suggests a structure.
Read next: Changelog · Notifications and email preferences
Frequently asked questions
What is the difference between a changelog and release notes?
Release notes describe what changed in a version of the software, often for technical readers. A changelog is written for customers: one entry per visible outcome, in plain language, ideally linked to the requests it resolves so the people who asked are told.
How often should you publish changelog entries?
Weekly or every two weeks suits most SaaS teams. A predictable rhythm matters more than the exact interval. Skip a quiet week rather than padding it, and break the rhythm only for urgent fixes or changes customers must act on.
Who should write the changelog?
Usually a product manager, drafting from the original customer request, with an engineer checking accuracy and support reading it before it goes out.
Should a changelog include bug fixes?
Yes, if customers noticed the bug. A Fixed entry tells the people who reported it that they were heard. Leave out internal fixes nobody could see.