What to Include in a Changelog: A PM's Checklist

You finished a sprint. Fourteen tickets closed. Now you need to write the changelog. You open a blank page and stare at your ticket list, trying to figure out which of these 14 items your users would actually care about.

The refactored database query? Probably not. The new export button? Definitely. The dependency update? Maybe, if it fixes a security issue. The CSS fix that took 3 days? Users never knew it was broken.

Most changelogs fail because they include everything or nothing. Here's the checklist for getting it right.

The Include/Skip Framework

Every completed ticket falls into one of three buckets:

Always include

New features. Any capability that didn't exist before. Users can now do something they couldn't yesterday. This is the core of your changelog.

"New: Export reports as PDF"
"New: Slack notifications for completed tasks"
"New: Dark mode"

User-facing improvements. Changes that make existing features noticeably better. Speed improvements, UX refinements, workflow shortcuts. If a user would notice the difference, include it.

"Improved: Dashboard loads 60% faster"
"Improved: Search now supports partial matches"
"Improved: Drag-and-drop reordering in project lists"

Bug fixes that users reported. If a user took the time to report a bug, they want to know it's fixed. Name the fix specifically enough that the reporter recognizes it.

"Fixed: CSV exports no longer timeout on datasets over 10,000 rows"
"Fixed: Email notifications were being sent twice for some accounts"
"Fixed: Calendar view showed incorrect dates in certain timezones"

Breaking changes. Anything that requires user action. API changes, deprecated features, removed functionality, changed defaults. These need to be prominent, not buried.

"Changed: API v1 endpoints will be retired on April 15. Migrate to v2."
"Changed: Default export format is now CSV (was XLS)"
"Removed: Legacy dashboard view"

Security updates. Users deserve to know when vulnerabilities are patched. You don't need to publish exploit details, but acknowledge the fix.

"Security: Patched a vulnerability in file upload handling"
"Security: Updated authentication flow to prevent session fixation"

Include selectively

Bug fixes that users didn't report. Internal bugs that users never noticed don't need changelog entries. But if the bug could have affected users even if nobody complained, include it.

Include: "Fixed: Rare issue where saved filters could reset after logout" Skip: "Fixed: Admin panel showed incorrect count on internal dashboard"

Performance improvements. Include if noticeable. Skip if marginal. "API response times reduced by 50%" belongs in the changelog. "Reduced memory usage by 3% on the background worker" doesn't.

Design changes. Include if the layout, navigation, or interaction patterns changed. Skip if it's purely cosmetic (color tweaks, font adjustments, spacing changes).

Never include

Internal refactors. "Migrated to React 19" and "Refactored the payment service" are engineering milestones, not user updates. Users don't care about your tech stack unless it affects their experience.

Dependency updates. "Updated lodash to 4.17.21" is noise. Exception: if the update fixes a security vulnerability or a user-facing bug, mention the fix, not the dependency.

Test improvements. "Added 200 new unit tests" is for your engineering blog, not your changelog.

Work-in-progress. Don't announce features that aren't fully shipped. Half-built features in the changelog create support tickets.

The Checklist

Before publishing a changelog entry, run through these questions:

Would a user notice this change? If they wouldn't notice without being told, consider skipping it.
Is it written in user language? "Reduced p95 latency on the GraphQL resolver" → "Dashboard loads faster." Translate technical work into outcomes.
Does it name the specific change? "Bug fixes and improvements" is the worst changelog entry possible. Be specific.
Is there a category? New, Improved, Fixed, Changed, Security, Removed. Categories help users scan for what matters to them.
Is there a date? Undated changelog entries are useless. Users need to know when something changed.
Are breaking changes at the top? If users need to take action, don't bury it below 8 other entries.
Is it under 2 sentences? Changelog entries are headlines, not blog posts. Link to a blog post or doc for details.

Writing Good Entries

The formula

[Category]: [What changed] + [Why it matters]

Each entry should be one or two sentences. The first sentence states the change. The optional second sentence adds context.

Good:

"New: AI-generated reports. Select your data range and Worknotes creates a summary you can share with stakeholders."
"Fixed: Email campaigns were failing for contacts with special characters in their names."
"Improved: In-app widget loads 3x faster on mobile devices."

Bad:

"We've been working hard on some exciting improvements to our platform!" (Says nothing.)
"Updated the email service to use a new SMTP provider with better deliverability rates and improved bounce handling." (Too technical.)
"Bug fixes." (Useless.)

Start with a verb

New, Added, Improved, Fixed, Changed, Removed, Security. Starting with the category or action verb makes entries scannable.

Write for scanners, not readers

Most users will scan your changelog in under 10 seconds. They're looking for one thing: "Is there anything here that affects me?" Make it easy:

Bold or highlight the feature name
Keep entries to one line when possible
Group related changes under one entry instead of listing 5 separate items
Put the most important entries first

How Often to Update

Weekly or biweekly works for most SaaS teams. This matches typical sprint cadences. If you ship continuously, batch changes into weekly roundups.

Per-release works for versioned products (mobile apps, desktop software, APIs). Each version gets its own entry.

Daily is too often for most products. Users don't check your changelog every day. Daily entries create a wall of text that nobody reads.

Monthly is too infrequent. A month of silence makes users assume nothing is happening. Even if you only shipped minor improvements, document them.

Grouping Entries

When you have 10+ changes in a single update, group them:

## March 2, 2026

### New
- AI-generated reports from your data
- Slack integration for real-time notifications

### Improved
- Dashboard loads 60% faster
- Search now supports partial matches

### Fixed
- CSV exports no longer timeout on large datasets
- Calendar displayed incorrect dates in some timezones

### Security
- Patched file upload vulnerability

This structure lets users jump to the section they care about. PMs scan "New." Engineers scan "Fixed" and "Security." Everyone wins.

The Automation Question

Writing changelog entries manually works for teams shipping 5-10 changes per sprint. Beyond that, the writing becomes a bottleneck. Someone has to review every ticket, decide what's user-facing, translate technical descriptions into user language, and format the entry.

Tools like Worknotes automate this process. Connect your issue tracker (Linear), select completed tickets, and AI generates user-facing entries from the ticket context. You review, edit, and publish. The writing is done. You just need to apply the checklist.

Whether you write manually or generate with AI, the checklist stays the same. The output needs to be specific, scannable, user-focused, and categorized.

Worknotes generates changelog entries from your Linear tickets using AI. Review, publish, distribute. $29/month. Start your free trial →