How to write a changelog people actually read

Most changelogs are written for the team that built the release. The ones people read are written for the person who uses the product and wants to know what's different today.

What makes a changelog worth reading?

• Titles that name the benefit. "Snooze a reminder for an hour" tells users something. "Reminder service improvements" doesn't.
• Short entries. One to three sentences. Link to docs for the details.
• A clear order. New features first, then improvements, then fixes.
• Dates on every entry, so users can tell an active product from a quiet one.
• A link back to the request when users asked for it, so they can see their feedback led somewhere.

How do you write a changelog entry?

1. Start from what the user can do now. Not what you built. "You can now export your streak history" rather than "Added CSV serializer."
2. Write a title with a verb and an outcome. "Export your streak history as CSV."
3. Explain what, where and why in the body. What changed, where to find it, and one line on why it helps.
4. Show it. A screenshot or short clip for any visible UI change.
5. Credit the people who asked. Name handles only if your community is public and people are comfortable being named.
6. Read it as a user. If a sentence needs knowledge of your codebase, rewrite it.

Here is the same change, before and after:

Before: feat(export): add csv serializer for streak model (#482)

After: Export your streak history. Go to Settings, then Data, and choose Export CSV to download every check-in with its date and habit. Thanks to @mira and 11 others who asked for this.

What's a good changelog template?

Use the same structure every time so readers know where to look:

## October 14, 2026

### New
**[Title: what you can do now]**
[What changed and where to find it. One line on why it helps.]

### Improved
- [Thing] is now [faster / clearer / easier to find].

### Fixed
- [The symptom users saw] no longer happens when [condition].

Write fixes as the symptom users noticed: "Reminders no longer fire twice after you change time zones." That's more useful than "Fixed race condition in scheduler."

Breaking changes go at the very top, with what users need to do.

How often should you publish a changelog?

Match your shipping rhythm. For most small teams, that's weekly or every two weeks. Batch small fixes into one entry rather than publishing ten one-liners. Skip a week rather than publish "minor improvements" with nothing behind it. A steady rhythm signals that the product is alive.

What should you leave out?

• Internal refactors, unless users notice the effect, such as faster load times.
• Ticket numbers and branch names.
• "Bug fixes and improvements" with no detail. It tells users nothing.
• Marketing language. Describe the change plainly. Users can judge if it's exciting.

How do you get people to see it?

A changelog nobody visits doesn't help. Push it out:

• Tell the voters. Email the people who asked for each shipped request. They're the readers most likely to care. See how to close the feedback loop.
• Reply where they asked. Post in the original Slack or Discord thread.
• Show it in the app. A small "What's new" link or badge.
• Link it from your roadmap. Each Shipped item on your public roadmap should point to its entry.

What are the common mistakes?

• Pasting commit messages. They're written for reviewers. If you want a head start, the release notes writer turns PR titles into user-facing drafts that you then edit.
• Burying breaking changes in the middle of a long entry.
• Writing for the team. "Migrated to the new queue" means nothing to users.
• Publishing irregularly, then all at once. Users stop checking.

Doing this with Sikia

Sikia's changelog is connected to your feedback board. When you publish an entry, Sikia emails everyone who voted for the requests it ships and replies in the original Slack or Discord threads. You can also publish from Claude Code or Cursor with the publish_changelog MCP tool.

FAQ

What's the difference between a changelog and release notes?

The terms overlap. A changelog is usually the running, dated log of changes, while release notes describe one specific release in more depth. For user-facing products, both should be written for users.

Should a changelog include bug fixes?

Yes, for fixes users would notice. Describe the symptom that's gone, not the cause in your code.

How long should a changelog entry be?

Usually a title and one to three sentences. If it needs more, write a docs page or blog post and link to it.

Should I follow the Keep a Changelog format?

It's a good convention for developer-facing libraries, with sections like Added, Changed and Fixed. For an app's users, a lighter version with New, Improved and Fixed is usually easier to read.