How to write a changelog customers read

By Hasan · November 5, 2026 · 5 min read

A changelog is a list of dated entries that tell customers what changed in your product. To write one well, start each entry with the customer benefit, say in two or three sentences what changed and where to find it, and publish entries newest first. In JustOneCX you write and publish entries in the Roadmap & Changelog module, and customers can mark each one helpful.

What should one changelog entry contain?

Keep every entry to the same shape. Readers learn the shape and scan faster.

  1. A title that names the change. Use the words a customer would use. "Export reports as CSV" is better than "Reporting module v2".
  2. One sentence on the benefit. What can the customer do now that they could not do before?
  3. Two or three sentences of detail. Where is it? How do they start?
  4. A link or a picture, if it helps. A link to the page, or a screenshot of the new screen.

Leave out internal ticket numbers, code names and long lists of small fixes. If you fixed a dozen small bugs, one line is enough.

How do you use your customers' words?

Write the way the customer asked. If ten people voted for "Add a Zapier integration", the entry title should say "Zapier integration". Do not rename it to something that sounds more like your team.

This is also why the changelog works well next to an ideas board. The idea already has the wording, the votes and the people who care. When the idea is done, the entry can reuse its words. The same idea is covered in the feedback board to changelog guide.

Do not copy a person's comment into a public entry without their permission. Describe the request in your own sentence instead.

How does an idea become a changelog entry?

In the Roadmap & Changelog module the path is short.

  1. A customer submits an idea, or you add one yourself.
  2. You move it through the roadmap: Planned, In progress, Shipped.
  3. When you mark it Shipped, its voters get an email and a changelog draft is created for it.
  4. You edit the draft in the Changelog tab and publish it. Optionally, publishing also shows a banner in your product that links to the entry.

Nothing reaches the changelog until you publish it. For a change that no customer asked for, you can write an entry directly in the Changelog tab.

Where do customers see the changelog?

You turn each place on or off in Roadmap & Changelog > Publish. All of them show the same entries, newest first.

  • On your website, with an embedded board. See the embed guide in the docs.
  • On your own subdomain, such as roadmap.yourcompany.com. See roadmap custom domain.
  • On the hosted page at boards.justonecx.com/<workspace-slug>/changelog.

The embed for a plain HTML page is one element:

<justonecx-changelog></justonecx-changelog>

Put it after the SDK script tag, or call mountChangelog from your framework code after mount.

Each entry has its own link, for example under /<workspace-slug>/ideas/... for ideas. You can also turn on Offer an RSS feed of the changelog in the Publish tab. It serves a feed at /<workspace-slug>/changelog/feed.xml. It is off by default.

What is the helpful signal?

Visitors can mark a changelog entry helpful. It is a one-click response. It tells you which entries customers found useful, without asking them to write anything.

Use it as a hint, not as a score. If an entry gets no response, it may simply be a change few people use. Look at the wording and the placement before you change your plan.

How does the What's new panel work?

The What's new panel shows your changelog inside your product. It has a badge for unread entries. It opens from your own button or from a floating button the SDK adds.

Turn it on under Roadmap & Changelog > Publish > On your website. Then add an attribute to any button:

<button data-justonecx-whats-new>What's new</button>

An entry is unread when it was published after the visitor last opened the panel. Identified visitors keep that state across devices. The full setup is in the What's new widget article.

What is the difference between a changelog and an announcement?

An announcement is a message that appears in your product for a chosen audience, such as a modal or a banner. A changelog is the permanent record. Announcements you publish in your product do not add changelog entries. Read announcement vs changelog to decide which one fits.

How often should you publish?

Publish when something ships. A short entry the same week is better than a long entry a month later. Keep a steady rhythm so customers learn that the page is current. An empty or stale changelog signals that nothing is happening.

Frequently asked questions

Does a Shipped idea publish itself to the changelog?

No. Marking an idea Shipped creates a changelog draft and emails the voters. You edit the draft and publish it. Nothing reaches the changelog until you do.

Can I show a banner when I publish an entry?

Yes. Publishing can optionally show a banner in your product that links to the entry.

Is the changelog newest first?

Yes. Visitors see published entries newest first and can mark an entry helpful.

Can the changelog be private?

Yes. Set the access mode to Private in the Publish tab. Only customers you signed in with a verified identity can read it.

See how it works in the live demo.

See it working in 2 minutes

Try the live demo

Related