Product Changelog

Product Changelog

When to Use This Skill

Use this skill when you need to:

• Create a changelog format and template for ongoing product updates
• Write user-friendly version notes for a product release
• Categorize changes into new features, improvements, and bug fixes
• Establish a consistent changelog cadence and style

DO NOT use this skill for internal release notes (engineering-facing), feature announcements (marketing-facing), or technical API documentation. This is for user-facing product changelogs.

Core Principle

A CHANGELOG BUILDS USER TRUST BY SHOWING CONTINUOUS IMPROVEMENT — WRITE EVERY ENTRY SO A NON-TECHNICAL USER UNDERSTANDS WHAT CHANGED AND WHY IT MATTERS TO THEM.

Phase 1: Brief

Required Inputs

GATE: Confirm the brief before writing.

Phase 2: Structure

Category System

Every change falls into one of these categories:

• New — Features or capabilities that did not exist before
• Improved — Enhancements to existing features (performance, UX, expanded functionality)
• Fixed — Bug fixes and issue resolutions
• Removed (use sparingly) — Deprecated features with migration guidance

Entry Format

Each changelog entry follows this structure:

### [Date or Version]

**New**
- **[Feature name]** — [What it does and why it matters in one sentence]

**Improved**
- **[Feature name]** — [What changed and the user benefit]

**Fixed**
- **[Issue description]** — [What was broken and confirmation it is resolved]

GATE: Confirm the category system and format before writing entries.

Phase 3: Write

Writing Rules

• Lead with the benefit, not the technical change. "Invoices now send 3x faster" beats "Optimized invoice queue processing."
• One sentence per entry. If it needs more, it deserves a feature announcement.
• Use active voice. "You can now export to PDF" not "PDF export has been added."
• Be specific about fixes. "Fixed: Emails with attachments over 5MB failed to send" not "Fixed email bug."
• Group related changes. If 3 fixes relate to the same feature, list them under one sub-heading.

Tone Guide

• Conversational but professional
• Celebratory for big features ("We have been working on this one for months...")
• Matter-of-fact for fixes (acknowledge, confirm fixed, move on)
• No apologies for bugs — just fix and state clearly

Entry Length Guide

Phase 4: Polish

1. Changelog Page Template

Provide a recommended page layout:

• Product name and "Changelog" or "What's New" header
• Filter/search by category (New, Improved, Fixed)
• Subscribe option (email or RSS)
• Archive with expandable months or pagination
• Link to roadmap or feature request board

2. Distribution Plan

• In-app: Badge notification on changelog link when new entries exist
• Email: Monthly digest of changes for subscribers
• Social: Highlight major features in a dedicated post
• Blog: Full write-up for major releases only

3. Quality Checklist

## Changelog Quality Checklist

- [ ] Every entry starts with a benefit, not a technical description
- [ ] Changes are categorized as New, Improved, or Fixed
- [ ] Each entry is one sentence (major features may use 2-3)
- [ ] Active voice used throughout
- [ ] Bug fixes describe what was broken specifically
- [ ] No jargon — readable by non-technical users
- [ ] Date or version number is included
- [ ] Deprecated features include migration guidance
- [ ] Subscribe/notification option exists for the changelog page

Example

### February 15, 2026

**New**
- **Recurring invoices** — Set any invoice to automatically send on a schedule (weekly, monthly, or custom). Find it under Invoice Settings.
- **Client portal** — Your clients can now view all their invoices and payment history in one place. Share the link from any client profile.

**Improved**
- **Dashboard loading speed** — Dashboard now loads 60% faster, especially for accounts with 500+ invoices.
- **CSV exports** — Exports now include payment status and date columns by default.

**Fixed**
- **Tax calculation on discounted items** — Tax was calculated before the discount was applied, resulting in overcharges. Now calculates correctly on the discounted amount.
- **Email notifications** — Some users were not receiving payment confirmation emails. Resolved for all accounts.

Anti-Patterns

• Technical jargon — "Refactored the webhook handler" means nothing to users. Translate to impact.
• Vague fix descriptions — "Fixed a bug" tells users nothing. Be specific about what was broken.
• Skipping updates — inconsistent changelogs erode trust. Ship on your stated cadence, even if it is a small update.
• Marketing fluff in changelogs — save the hype for feature announcements. Changelogs should be factual and scannable.
• No categorization — a flat list of changes is hard to scan. Always categorize.

Recovery

• Very few changes this cycle: Combine with the next cycle, or ship a brief update noting improvements and behind-the-scenes work.
• Breaking change included: Lead with the breaking change, explain what users need to do, and provide a migration guide link.
• User-reported bug is fixed: Consider naming the fix in a way that acknowledges the report: "Fixed (thanks for reporting!): [description]."
• No changelog exists yet: Create a retroactive launch entry summarizing the product's current capabilities, then begin regular updates.