A changelog is the simplest proof that your product is alive. Customers check it before they renew, prospects skim it during evaluation, and support teams link to it when a bug they reported is fixed. Yet many changelogs are either a dump of commit messages or a page that hasn't been touched in a year.
This guide covers how to structure entries, which categories to use, how often to publish, and gives you a template. At the end we show how to publish it as a hosted page and an in-app widget with Nitrozen.
Who the changelog is for
There are two audiences, and they want different things:
- Developers integrating your software want precise, versioned lists of what was added, changed, deprecated, removed and fixed. The community convention Keep a Changelog is written for this audience.
- Customers using your product want to know what they can do now that they couldn't before, and whether anything they rely on changed.
Most SaaS teams need the second kind, a product changelog, and sometimes the first as well for an API or SDK. Decide which you're writing before you start, because it changes the language. (More on that in changelog vs release notes.)
Anatomy of a good entry
Every entry should answer three questions in its first two sentences: what changed, why it helps, and where to find it.
- A benefit-led title. "Export reports to CSV" beats "Export improvements". "Fixed login loop on Safari" beats "Bug fixes".
- A date (and a version number if customers install your software).
- A category. Readers scan for what affects them.
- One to three sentences written from the user's side: what they can do now and how.
- A visual for anything they'll see: a screenshot or short GIF.
- A link to the docs, setting or feature.
Categories that work
Keep a small, fixed set so the log stays scannable. Keep a Changelog uses Added, Changed, Deprecated, Removed, Fixed and Security. Product changelogs often simplify this to:
- New: a feature that didn't exist before.
- Improvement: an existing feature got better.
- Fix: something broken now works.
- Announcement: pricing, policy, deprecations or company news.
Whatever you pick, use the same labels every time. Nitrozen ships with New, Improvement, Fix and Announcement as colour-coded badges for exactly this reason.
Writing style
- Lead with the outcome, not the implementation. "Dashboards load faster on large accounts" instead of "Refactored the query layer".
- Use "you". It forces you to describe a user-visible result.
- Be specific. "Search now matches partial email addresses" is useful; "Improved search" isn't.
- Admit bugs plainly. "Fixed a bug where invoices showed the wrong currency" builds more trust than vague wording.
- Skip internal jargon. Ticket numbers, branch names and codenames belong in internal notes.
- Flag breaking changes first with the action required and a deadline.
How often to publish
Consistency matters more than volume. Pick a rhythm you can sustain (every release, weekly or every two weeks) and stick to it. If a week is quiet, batch small fixes into one "quality improvements" entry instead of going silent. A changelog that hasn't moved in months makes an active product look abandoned.
The easiest way to stay consistent is to make the entry part of "done": whoever ships a user-visible change writes a two-line draft while the context is fresh. Teams that release through GitHub can automate this; see automating your changelog from GitHub Releases.
Template
Copy this for each entry:
## [Benefit-led title]
**Category:** New | Improvement | Fix | Announcement
**Date:** YYYY-MM-DD
[One sentence: what you can do now.] [One sentence: why it matters or what problem it solves.]
**How to use it:** [Where to find it, e.g. Settings → Notifications → Email digest.]
[Link to docs →]
Example
## Get a weekly email digest of new comments
**Category:** New
**Date:** 2026-10-28
You can now receive one summary email each Monday instead of a notification for every comment. It's on by default for new workspaces and off for existing ones.
**How to use it:** Settings → Notifications → Weekly digest.
Make it easy to find
A great changelog nobody sees doesn't help. Put it in at least three places:
- A public page at a memorable URL such as
/changelogorchangelog.yourdomain.com, linked from your footer and help centre. - Inside the product, through a "What's new" widget, so active users see updates without leaving the app. See how to add a what's new widget.
- Where customers already are: link notable entries in your newsletter, social posts and support replies.
Publish it with Nitrozen
Nitrozen is a changelog platform built for this workflow:
- Write entries in Markdown with category badges.
- Publish to a hosted public changelog page, with custom domain support on paid plans.
- Show the same entries in your app with an embeddable widget added via one script tag.
- Automate from your pipeline with the REST API, SDKs for Node.js, Python and Go, a GitHub Action, or let an AI assistant draft entries through the MCP server.
The free plan includes one project, five entries a month, a public page and the widget, so you can start today.