How to write a product changelog customers read

Customers notice software when it changes under them. Learning how to write a product changelog is the habit of publishing a short, dated list of notable changes for each version, written for the people who use the product rather than for the people who committed the code. You group what was added, changed, fixed, or removed, put the newest release first, and make breaking changes easy to find.

Keep a Changelog, as of November 2026, defines a changelog as a curated, chronologically ordered list of notable changes for each version of a project. The goal is to help users and contributors see precisely what changed between releases. A raw commit history is full of merge noise and private nicknames that do not help a customer decide what to do next.

This post is a writing method you can use even if you never open a release-notes product. Where Nautis appears, it is one place to draft the entry in Notes and export a file you can paste onto your public page.

What a changelog should tell a customer

A useful entry answers five questions in plain words:

1. Which version is this, and when did it ship?
2. What can I do now that I could not do before?
3. What behaves differently than last week?
4. What will break if I ignore this note?
5. What did you fix that I might have already felt?

If those five are blank, you have a status update for engineers. Fill them before you publish. Keep a Changelog's guiding principles, as of November 2026, say changelogs are for humans, every version should have an entry, similar changes should be grouped, the latest version comes first, and each version should show its date.

The same page asks you to mention whether you follow Semantic Versioning (SemVer). Semantic Versioning 2.0.0, as of November 2026, uses a major.minor.patch number: raise major for incompatible application programming interface (API) changes, minor for backward-compatible additions, and patch for backward-compatible bug fixes. You do not have to adopt SemVer to write a good changelog. If you do, say so and let the version number match the story you tell.

Founder scenario (example): Amir shipped three times a week and pasted branch titles into a shipping channel. Customers asked support whether export was already fixed two releases later. He started writing one public entry per version, grouped by Added, Changed, and Fixed, and linked it from the app footer.

How to write a product changelog entry by entry

Write the entry while the change is still fresh, not during the Friday scramble. Keep an Unreleased section at the top of the working draft, which Keep a Changelog recommends so you can move those lines into a dated version when you ship.

A practical writing sequence:

1. Collect the user-facing work that landed since the last published version. Walk pull requests, support tickets, and anything a customer would see.
2. Drop anything that does not change what a user can do, see, or rely on. Internal refactors belong in the commit history.
3. Group the remaining lines into types. Keep a Changelog uses Added, Changed, Deprecated, Removed, Fixed, and Security. Omit an empty group rather than writing "none."
4. Rewrite each line in customer language. Start with a verb the reader can picture: "Export a project as a comma-separated values (CSV) file" rather than "Wired CSV serializer into reports worker."
5. Put deprecations, removals, and breaking changes where nobody can miss them. Keep a Changelog says that if you do nothing else, list those clearly so people can upgrade in two steps: first to a version that warns, then to a version that removes.
6. Add the version, the date in year-month-day form such as 2026-11-08, and a one-line audience note when only some customers are affected.
7. Have someone who did not build the change read the draft out loud. If they cannot tell what to click, rewrite the line.

This is a lightweight process, closer to standard operating procedure (SOP) writing for startups without bureaucracy than to a legal review. The document should take minutes once the habit exists.

If you already try to ship something every week as a founder, the changelog is how that weekly motion becomes visible to the people who pay you.

Anatomy of one changelog entry

Use the same skeleton every time so readers learn where to look. The table below is an illustrative anatomy for a fictional 1.4.0 release, not a real customer story.

Keep a Changelog also describes yanked releases: versions pulled because of a serious bug or security issue. Those versions should still appear, marked clearly as yanked.

Write dates as year, month, then day. Keep a Changelog recommends that order because regional formats swap month and day and confuse readers across countries.

A strong line names the object and the outcome. Weak lines name the ticket or the file:

• Weak: "Fixes ticket 1842"
• Strong: "Fixed the export timeout on projects with more than 10,000 rows (illustrative threshold)"
• Weak: "Refactored billing service"
• Strong: omit it, unless a customer-visible invoice field changed
• Weak: "Improvements and bug fixes"
• Strong: list the two fixes people actually hit

When a change needs a longer how-to, link from the entry to a help article. Do not hide the breaking change inside that link. The changelog line should still say what stopped working.

How often should a startup publish a changelog?

A startup should publish a changelog every time it ships a version customers can notice, and add a standing weekly note only when many small versions would otherwise pile up unread. The unit is the version, not the calendar, which matches Keep a Changelog's rule that there should be an entry for every version.

Practical cadence for a small team:

• If you ship one customer-facing version a week, publish when that version goes live.
• If you ship daily internal builds, collect them under Unreleased and publish when you tag the version customers receive.
• If you batch a month of quiet fixes, publish a short dated entry instead of waiting for a launch post.
• If you had to pull a version, publish the yanked notice the same day.

Keep a Changelog warns that a changelog which only mentions some of the important changes can be as dangerous as having none, because readers treat the page as complete. If you skip a breaking change, people will assume nothing broke. Set a simple owner rule: a version is not shipped until the public note exists, even if that note is four lines long.

Who writes it, and who signs off?

The person closest to the user-facing change writes the first draft, and someone who did not build the change reads it before it goes public. On a three-person team that often means the founder writes, an engineer checks technical facts, and whoever talks to customers checks tone.

A short review checklist:

• Does every line describe something a user can observe?
• Are breaking changes, deprecations, and removals impossible to miss?
• Do version numbers match what you say, especially if you claim SemVer?
• Is any line copied from a commit title that only the author understands?
• Did you include a yanked or security note when one exists?

Do not wait for a marketing hire. A later launch essay can sit on top of this record. The changelog stays the factual layer underneath.

In Nautis, keep the working Unreleased draft in Notes. Notes is a rich-text workspace with folders, tags, comments, sharing, and export to Portable Document Format (PDF) or Word. Share it with the people who review releases and export a copy if someone outside the workspace needs the text.

Where should customers find each new entry?

Customers should find each new entry on a public changelog page, with the same text reused in the product or in a short email when the change affects how they work. One source document, several doorways.

Useful doorways:

• A public changelog page on your site, newest first, each version easy to link
• An in-app "What is new" panel after an admin logs in following a release
• A short email to workspace admins when a change is breaking, deprecated, or security-related
• A changelog file in the repository, often named changelog.md, if developers or technical buyers read your code

GitHub Releases can hold rich notes for people who already live in GitHub. Keep a Changelog notes that those notes are not very portable or easy for ordinary end users to discover, so do not let GitHub be the only copy if your buyers never open the repo.

Reuse the same sentences everywhere. Rewriting the story for email, then again for the blog, is how a "small copy tweak" becomes two conflicting dates.

When you publish, link the version heading so someone can paste a uniform resource locator (URL) into a support reply.

What should you leave out of a public changelog?

Leave out internal refactors, commit hashes, and any change that does not change what a user can do, see, or rely on. Also leave out jokes that hide a breaking change, and vague buckets such as "various improvements."

Skip these lines unless a customer can act on them:

• Dependency bumps with no user-facing effect
• Renamed private functions or cleaned comments
• Work that is still behind a flag nobody can turn on
• Roadmap teases or "coming soon" items, which belong in a separate note

Keep a Changelog argues against using commit log diffs as the published document. The purpose of a commit is to record a step in the source. The purpose of a changelog entry is to record the noteworthy difference, often across many commits, for a human who was not in the repository that week.

If you are unsure whether a line belongs, ask whether a customer would change their Friday because they read it. If the answer is no, delete the line. The page should stay short enough that an admin will actually finish it.