How to Write Changelogs Your Users Will Actually Read

Shayan, FounderUpdated 13 min read

Cover image for How to Write Changelogs Your Users Will Actually Read.

What separates a product changelog customers actually read from one they ignore is simple. A good changelog tells people what they can do in the product today that they couldn't do last week, in the plain words they use to do their job, without making them decode internal engineering tickets or wade through marketing fluff.

Most changelogs miss that mark because of when they get written. By the time a release is ready to go out, the engineers have already moved on to the next sprint and the person pulling the update together just wants to hit publish before logging off. So someone copies the pull request titles straight out of GitHub, or someone else dresses up three minor tweaks as a "major workflow upgrade," and neither version answers what a customer opening the page came to check.

You can see the codebase-first habit even in products that care about documentation. In GitLab's internal changelog guide for its own engineers, the team shows a real commit line an engineer wrote for a release:

Strip out nils in the Array of Commit objects returned from find_commits_by_message_with_elastic

To the engineer who spent the afternoon debugging that method, the sentence is completely accurate. To a customer whose search page kept throwing a 500 error, it might as well be written in another language.

Below is how to turn rough engineering notes into changelog entries customers actually want to read, with four before-and-after rewrites, a scannable structure for your updates, tips on screenshots and code snippets, and how to close the loop with the users who asked for the feature.

How to write a changelog entry, with before and after examples

When you've spent three days inside a pull request fixing a race condition or refactoring a permissions check, the code change is the entire story in your head. When you sit down to write the changelog line, your instinct is to describe what you did to the code.

Your customer has never seen your repository. They only know the screen they were on, the button they clicked, and the wall they hit. Every good changelog edit is just flipping the sentence around so it starts from the user's side of the screen.

1. Name the symptom the user saw, not the function you fixed

Take that GitLab search bug from the intro. Nobody outside GitLab's engineering team knows what find_commits_by_message_with_elastic is or why an array of commit objects had nil values in it. Here is how GitLab rewrote the exact same fix for its public changelog:

Fix 500 errors caused by Elasticsearch results referencing garbage-collected commits

Now anyone who ran into a 500 error while searching commits recognizes their problem immediately and knows they can drop their workaround.

While you're editing bug fixes, strip out internal issue numbers and merge request codes unless links point to a public open-source repository. On 1Password's Mac changelog for version 8.12.42, a clear, helpful line like "1Password Environments now support up to 25 local .env file destinations per computer" ends with #DW-1436 !41964. Those internal Jira and GitLab IDs help QA track the build, but on a customer-facing page where nobody can click them, they just clutter the sentence.

2. State what the user can do now, and what it was like before

On new features, teams usually fall into one of two traps. Either they write an internal spec label, or they spend three sentences congratulating themselves on an "exciting new experience" without saying what changed on screen.

Here is how an internal ticket for a support portal redesign usually reads:

Refactored customer support portal ticket view from modal widget to full-page route with sidebar metadata.

And here is how Intercom actually announced that update on its changelog on October 29, 2026:

Your customers' support portal now works more like a real inbox. Conversations and tickets open on their own full-page, shareable screens instead of a floating widget, with ticket details alongside.

Two details make Intercom's version click on the first read. First, it describes what you see on screen rather than how the router was built. Second, it includes the phrase "instead of a floating widget". Naming how the product worked yesterday is the fastest way to orient a reader who hasn't opened that screen in a few weeks.

Stripe uses that same now-and-previously structure across its API changelog. When Stripe made subscription trial offers generally available in its 2026-09-30 release, the entry opened with:

Adds Trial Offers for subscriptions, which define reusable free or paid introductory pricing for individual Subscription Items, each with their own price and billing period. Previously, a subscription used a single trial period for the entire subscription.

Whenever you're stuck on how to explain a feature without sounding like a press release, write one sentence starting with what the user can do now, followed by one sentence starting with "Previously,".

3. Reassure users when a setting moves or gets renamed

Teams almost always forget to write changelog entries for renamed tabs, moved settings, or updated defaults because no new capability shipped. Then a customer logs in ten minutes before a demo, follows a muscle-memory click path or an older tutorial, and panics because the feature appears to be gone.

A typical one-liner in a sprint roundup looks like this:

Updated the Database sidebar navigation and renamed the Replication section.

Compare that to how Supabase announced a navigation rename on September 21, 2026:

Database > Replication is now Database > Pipelines. Existing Replication URLs redirect to the new location. No API or pipeline behavior has changed.

In three short sentences, Supabase gives the exact old path, the exact new path, and the two reassurances every developer wants before they file a support ticket: old bookmarks still redirect, and nothing in production changed. Stating what didn't change is often just as helpful as stating what did.

4. Give the old and new numbers instead of saying "faster" or "bigger"

Every software company claims its latest release is faster, smoother, and more reliable. Because customers see those words on every app update, they skim right past them.

Instead of writing:

Improved container registry uploads and increased layer size limits so your builds run faster.

Write what Vercel published on its changelog on October 28, 2026:

Vercel Container Registry now supports 2 GB compressed image layers. Push compressed image layers up to 2 GB, up from 500 MB.

Giving the new limit and the old limit takes fewer words than the vague version, and any engineer whose build failed on a 600 MB image last month knows at a glance that the blocker is gone.

How to structure a changelog so people can scan it

Nobody pours a cup of coffee to read your changelog from top to bottom. Customers open the page to scan the last few updates in fifteen seconds, looking for the parts of the product they actually use.

Start by putting the change itself in the headline of each entry. Titles like October Product Update or Release v2.14 force the reader to read every paragraph just to find out whether the update affects them. Write a title that states the outcome, like Plausible's "Flexible funnels" or Shopify's "Manage variants directly on the product detail page", and put a calendar date on every post. Both active users debugging an issue and prospective buyers checking your footer look at the dates first to see if your product is actively maintained.

When an entry covers several updates at once, group them under predictable headings like New, Improved, and Fixed so readers can jump straight to what they care about. On a standalone changelog feed, stick to a small set of badges for the change type or tag posts by product area, the way Paddle tags entries with Transactions, Checkout, Paddle.js, and API. If you want copyable Markdown structures for weekly roundups, breaking API changes, or mobile store updates, grab the six outlines in our release notes template guide, or see what is a changelog for the repository CHANGELOG.md specification.

Finally, always tell the reader who gets the feature and where to find it. Few things frustrate a SaaS customer more than reading about a new capability, switching over to the app, and spending five minutes hunting for a button that is gated to the Enterprise plan or turned off by default in workspace settings. Zapier prevents that confusion by ending every changelog entry with an Availability line naming the exact plans that include the update, while Intercom spells out the navigation path, such as Settings > Channels > Messenger, right in the post.

A good visual saves the reader from having to picture where a new control lives in your interface, provided the image actually shows the change at readable scale.

When you add a screenshot to a changelog post, crop into the specific menu, dialog, or table that changed rather than pasting a full-screen capture of your entire browser window where every label is four pixels tall. On Notion's and Linear's changelogs, a tight screenshot or a five-second screen recording right below the opening paragraph shows the click path immediately.

If you build a developer tool, CLI, or API, skip screenshots of terminal windows and use a short code block instead. In esbuild's and Prettier's changelogs, entries regularly include a three-to-five-line snippet showing the syntax or configuration before and after the change, which developers can read and copy in seconds.

Use links to keep your changelog entries short. A changelog post is an announcement, not a ten-step setup manual. Give the reader enough context to understand what the feature does and where to turn it on, then link straight to your help center guide or API reference for the configuration details, the way Shopify, Clerk, and Stripe do on every update.

Match your cadence to how you ship, and skip the filler

The most common reason SaaS changelogs die is that teams treat every post like a press release. A week goes by where the team mostly fixed bugs, sped up a slow query, and polished a few forms. Someone in Slack says, "We didn't ship anything big enough for a changelog post this week, let's wait until the new dashboard is ready." Two sprints slip, and suddenly a prospect clicking "Changelog" in your website footer finds a page whose newest post is from seven months ago.

You don't need a major launch to update your changelog. If your team ships small improvements every day, you can follow Buttondown's format and post a single dated sentence per change starting with a verb:

Stopped asking you to confirm deleting a nearly empty draft (thanks, Marcin!)

Fixed confirmed duplicate emails getting blocked when sent (thanks, Etienne!)

If you prefer a weekly rhythm, follow the pattern used by Neon, Railway, and Raycast: publish one dated roundup at the end of the week with the biggest change at the top and a Fixes & improvements list underneath for the smaller work.

The one habit to avoid is publishing an update whose only message is that you have nothing to tell the reader. On October 26, 2026, Slack shipped version 4.53.269 of its Mac app with this release note:

We don't have anything in particular to call out for this release, but we thank you for staying up to date all the same.

Two months earlier, Slack's Mac note opened with "Nothing major to report this week. Nothing minor to report either, as it turns out." If a deployment genuinely consists only of internal refactoring that changes nothing a customer can see or feel, don't publish a changelog post for it. And if the release fixed real bugs, name the symptoms those bugs caused, as we covered in our release notes guide.

Put updates where active users will see them, and close the loop

Hosting a public /changelog or /updates page on your website gives your product a permanent record. Prospective buyers read it during evaluation to see your shipping velocity, power users subscribe to it, and your support and sales teammates rely on having a dedicated URL per entry that they can paste into customer conversations.

Still, almost none of your active customers wake up on Tuesday morning and type your marketing URL into their browser just to check /changelog. They log straight into your app to do their work. If you want existing users to actually discover and try the features you ship, surface your updates inside the product using an in-app widget that shows an unread badge or a quiet prompt when a new post goes live.

Most importantly, connect your changelog back to the customers who asked for the update in the first place. Most software users are used to submitting a feature request and never hearing another word about it. When you email everyone who voted or commented on a request to tell them their idea just shipped, and link their original request thread right under the changelog post, those users show up on day one to try the feature. They also learn that giving your team feedback actually leads to shipping software.

Write your changelog from the requests you shipped.

Juno, the assistant in UserJot's changelog editor, reads the customer requests you completed since your last post and writes a highlighted draft with the title, tags, and linked requests filled in. Free to start.

Try UserJot free

How UserJot turns completed requests into changelog posts

The hardest part of writing a changelog on Friday afternoon is reconstructing what shipped from scattered pull requests and Slack threads. When your feedback board, public roadmap, and changelog live in the same workspace, the customer requests you completed during the week are already your outline. The customer's original post gives you the problem in plain English, and their title is already written from the user's side of the screen.

In UserJot, marking a request Completed moves it to the Done column on your roadmap and automatically sends an email to everyone who posted, voted, or commented on it. When you open the changelog editor to write your public update, Juno, our editor assistant, lists the requests you completed or closed since your last post, reads their descriptions and comment threads, and writes a highlighted draft with the title, date, tags, and linked requests filled in. You review and edit her draft before publishing, as Juno never publishes on her own.

Once you hit publish, the post goes live at /updates on your board with its own permanent URL and the original customer requests linked underneath as "Built from your feedback". Inside your app, the in-app widget can increment its unread badge or expand the launcher pill with the post title so signed-in users see what's new right where they work. Changelog publishing and Juno in the editor are included on every plan, including Free.

The UserJot changelog editor: a product update about a mobile app, with Juno drafting its opening from the requests that shipped.

Frequently asked questions

How do you write a good changelog entry?

Start with what the user can do now in plain, everyday language, and follow it with a "Previously..." sentence whenever naming the old behavior makes the change clearer. State which plans or platforms include the update, tell the reader whether they need to take any action, and link to the documentation for setup steps.

What should you leave out of a customer changelog?

Leave out internal refactoring, test suite changes, dependency bumps that don't affect users, and raw git commit messages. Unless you are maintaining an open-source developer changelog where readers click into pull requests, strip out internal Jira ticket codes and merge request numbers too.

How long should a changelog entry be?

Make each entry only as long as the user-visible change requires. A quota increase or a menu rename takes two or three sentences, while a major new workflow takes one short paragraph, a cropped screenshot, and a link to the help docs. For minor bug fixes and polish shipped alongside a bigger feature, a one-line bullet per fix at the bottom of the post is plenty.

How often should you update your changelog?

Publish an entry whenever you ship a change that customers can see, or batch smaller updates into a predictable weekly or biweekly roundup. A steady cadence matters much more than waiting for a massive launch, because a public changelog that hasn't been updated in six months makes an active product look abandoned to prospective buyers.

Should you include bug fixes in a product changelog?

Yes, as long as you describe the symptom the customer experienced rather than the code you changed. Instead of pasting "Bug fixes and performance improvements", write a single line naming the screen and the broken behavior, such as 1Password's note that the Safari browser extension couldn't connect to the desktop app. Most SaaS teams group these one-liners under a Fixes & improvements heading at the bottom of their weekly or feature post.

How do you get users to actually read your changelog?

Put the updates inside your product rather than waiting for customers to visit your marketing website. An in-app widget that shows an unread count or displays the headline of a new post reaches active users while they are already logged in. Closing the loop by emailing the customers who voted on a feature request when you mark it Completed also brings your most engaged users straight to the update.