How to Write a Changelog: The Complete Guide

A changelog is one of those things every SaaS product should have but most do poorly. The concept is simple: a chronological list of changes to your product. The execution is where it falls apart. Teams start with good intentions, update it for a few weeks, then quietly stop. The last entry is from months ago. Nobody mentions it.

This guide covers how to write a changelog that's actually useful, how to keep it current, and how to avoid the patterns that make changelogs go stale.

What a changelog is (and isn't)

A changelog is a public, chronological record of notable changes to your product. It answers one question for users: "What's different since the last time I checked?"

A changelog is not:

Release notes. Release notes are narrative documents about specific releases. They tell a story. Changelogs are running lists. Both are useful. They serve different purposes.
A commit log. Your git history is for developers. Your changelog is for users. "Refactored auth middleware" is a commit message. "Login is faster and more secure" is a changelog entry.
Documentation. Docs explain how things work. Changelogs announce that things changed. Link to docs from your changelog when a new feature needs explanation.
A marketing blog. Blog posts sell a narrative. Changelogs inform. The tone should be clear and factual, not promotional. Save the storytelling for your blog.

The difference between changelogs and release notes matters because it determines your format, tone, and audience expectations.

What goes in a changelog

Include

New features. Anything users can now do that they couldn't before. "New: Export reports as CSV" or "New: Dark mode across all pages."
Improvements. Upgrades to existing features. "Improved: Dashboard loads 3x faster" or "Improved: Search now supports filters by date range."
Bug fixes. Fixes that affected user experience. Be specific: "Fixed: File upload failing for files over 25MB" not "Fixed various bugs."
Breaking changes. Anything that changes existing behavior. Flag these prominently. "Breaking: API v1 endpoints will redirect to v2 starting April 1."
Deprecations. Features being removed or phased out. Include timelines and migration paths.
Security updates. Patches for vulnerabilities. You don't need to describe the vulnerability in detail, but acknowledge the fix.

Exclude

Internal refactors. Code reorganization that doesn't change user experience. Users don't care that you migrated to a new ORM.
Dependency updates. Upgrading React from 18 to 19 isn't a changelog entry unless it changes something users can see or feel.
CI/CD changes. Your deployment pipeline is invisible to users. Keep it that way.
Test coverage. "Added 47 unit tests" is great for your team. It means nothing to your users.
Tiny copy changes. Changing "Submit" to "Save" on one button probably isn't worth an entry. Unless it's part of a larger UX overhaul.

The filter question: "Would a user who checks our changelog once a month care about this?" If yes, include it. If no, skip it.

How to structure entries

Use consistent categories

Pick a category system and use it every time. The most common:

New (or Added)
Improved (or Changed, Enhanced)
Fixed
Removed (or Deprecated)

Some teams add:

Security for security-specific patches
Breaking for breaking changes
Beta or Preview for early access features

Don't invent new categories per release. Consistency helps users scan quickly because they learn your system.

Date every entry

Every changelog update needs a date. "March 10, 2026" not "v2.4.1." If you use version numbers, pair them with dates: "v2.4.1 — March 10, 2026."

Dates create a timeline users can navigate. They also signal your shipping cadence. Weekly dates show momentum. Monthly gaps show stagnation.

Write benefit-first descriptions

The most important changelog writing practice is leading with the user benefit.

Feature-first (bad): "Added webhook retry logic with exponential backoff and configurable timeout."

Benefit-first (good): "Webhooks now retry automatically when delivery fails. Failed deliveries will retry up to 5 times over 24 hours, so you won't miss events during temporary outages."

The first version describes what the team built. The second describes what the user gets. Write the second one.

Keep entries short

One to three sentences per entry. If a feature needs more explanation, write a short entry and link to a blog post or documentation page.

Too long: "We've been working hard on improving our search functionality. After months of research and development, we're thrilled to announce that search now supports boolean operators, fuzzy matching, and field-specific queries. Boolean operators let you combine search terms using AND, OR, and NOT. Fuzzy matching finds results even when you misspell a term. Field-specific queries let you search within specific data fields like name, email, or status."

Just right: "Search now supports boolean operators (AND, OR, NOT), fuzzy matching for misspellings, and field-specific queries. Learn more in our docs →"

The changelog is a notification, not a manual.

Choosing your format

The rolling list

A single page with entries in reverse-chronological order. New entries at the top. The most common format and the easiest to maintain.

Best for: SaaS products shipping weekly. Users scroll to find what changed since they last checked.

Examples: Linear, Vercel, GitHub

The grouped release

Entries grouped by version or release date. Each group has a heading with the date/version and a list of changes underneath.

Best for: Products with distinct releases (mobile apps, on-premise software, APIs). Users look for a specific version.

Examples: Stripe, Figma

The narrative update

Each entry is a mini blog post with context, screenshots, and explanation. More editorial, less listicle.

Best for: Products where every change is significant and worth explaining. Usually B2B SaaS with fewer, larger releases.

Examples: Notion, Superhuman

Which should you pick?

For most SaaS teams shipping weekly, the rolling list is the right starting point. It's the easiest to maintain, the fastest to publish, and the format users expect. You can always graduate to narrative updates for major releases while keeping the rolling list for everything else.

Setting up your changelog

Option 1: Built-in page

Add a /changelog page to your product's website. This gives you full design control and keeps the changelog on your domain (good for SEO). You can build it with your existing stack: a simple page that reads from a CMS, database, or markdown files.

Pros: Full control, lives on your domain, no external dependencies. Cons: You have to build and maintain it. Design, routing, RSS, email integration are all on you.

Option 2: Dedicated tool

Use a changelog tool that handles the page, widget, and distribution. Options range from free (UserJot, basic changelog tools) to paid (Beamer, AnnounceKit, Worknotes).

Pros: Faster setup, built-in widgets, email distribution, analytics. Cons: Monthly cost, less design control (varies by tool), dependency on a vendor.

Option 3: GitHub Releases

If your product is open-source or developer-facing, GitHub Releases might be enough. Each release is tagged with a version number and includes a description. Users can watch the repo for notifications.

Pros: Free, integrated with your development workflow, familiar to developers. Cons: No in-app widget, no email distribution, limited formatting, not user-friendly for non-developers.

For most SaaS teams, a dedicated tool is the practical choice. Building a changelog page is straightforward. Building the distribution layer (email campaigns, in-app widgets, user segmentation) is where the real work lives. That's what tools solve.

Keeping it current

This is the hard part. Starting a changelog is easy. Maintaining it past week 6 is where most teams fail.

Make it part of your sprint ritual

The changelog update should be a line item in your sprint close process, not an afterthought. Sprint ends → changelog gets updated. Treat it like the retro: it happens every time, not just when someone remembers.

Assign ownership

"Everyone's responsible" means nobody's responsible. Assign changelog ownership to one person per sprint or permanently. This doesn't mean they write every entry. It means they make sure entries get written and published.

Lower the friction

The harder it is to publish a changelog entry, the less likely it happens. If publishing requires opening a CMS, writing HTML, uploading images, and deploying, that's too much friction. The process should take 15 minutes or less.

This is where automation helps most. Worknotes connects to Linear, reads completed tickets, and generates user-facing entries with AI. You review and publish. The writing, which is the highest-friction step, is automated.

Set a minimum cadence

Even if you shipped nothing user-facing (rare for active products), check the changelog at your regular interval. Either publish what's new or confirm nothing needs publishing. The habit matters more than the content of any single entry.

Common mistakes

Starting too formal

Your first changelog entry doesn't need to be perfect. Publish something. You'll refine the format over time. Teams that spend weeks designing the perfect changelog page often never publish a first entry.

Making it too granular

Listing every minor UI tweak and copy change buries the important updates. Users who see 40 entries per week will stop reading. Curate. Include what matters. A changelog with 5 meaningful entries per week beats one with 30 trivial ones.

Forgetting distribution

A changelog page without distribution is a tree in an empty forest. Pair your page with email campaigns for reach and in-app announcements for active users. Publishing is half the job. Distributing is the other half.

Treating it as marketing

The fastest way to lose changelog trust is turning it into a marketing channel. Users expect factual updates, not sales pitches. "New: Export to CSV" is a changelog entry. "Transform your workflow with our revolutionary new export experience!" is marketing copy that makes users distrust everything else on the page.

Going silent

The worst thing a changelog can do is go silent. An empty changelog tells users the product is abandoned, even if your team is shipping every week. If you can't maintain the changelog, remove the page entirely. A stale changelog is worse than no changelog at all.

Getting started today

If you don't have a changelog yet, here's the fastest path:

Pick your format. Rolling list for most teams.
Choose your tool. Built-in page if you have engineering time. Dedicated tool if you don't.
Write your first entry. What did you ship this week? Write 3-5 entries. Publish them.
Set your cadence. Weekly is ideal. Biweekly is fine. Monthly is the minimum.
Distribute. Link to the changelog from your app's navigation. Add it to your email signature. Tell users it exists.
Maintain. Add the changelog update to your sprint checklist. Don't let it slide.

The best changelog isn't the most beautifully designed or the most detailed. It's the one that's always current. Start simple, publish consistently, and improve over time.

Worknotes generates changelog entries from your Linear tickets, then distributes them via email and in-app widgets. $29/month flat. Start your free trial →