Release Notes

Release Notes

When to Use This Skill

Use this skill when you need to:

• Write release notes for a software update or new version
• Communicate breaking changes with migration guides
• Document known issues and workarounds for a release
• Create release notes that serve both technical and non-technical audiences

DO NOT use this skill for product changelogs (ongoing, shorter entries), feature announcements (marketing-focused), or internal engineering post-mortems. This is for formal release notes tied to a specific version or update.

Core Principle

RELEASE NOTES SERVE TWO AUDIENCES SIMULTANEOUSLY — USERS WHO WANT TO KNOW WHAT CHANGED AND DEVELOPERS WHO NEED TO KNOW WHAT BROKE. WRITE FOR BOTH.

Phase 1: Brief

Required Inputs

GATE: Confirm the brief before writing.

Phase 2: Categorize Changes

Sort every change into one of these categories:

• Highlights — Major features or changes worth calling out at the top
• New Features — Capabilities that did not exist before
• Improvements — Enhancements to existing functionality
• Bug Fixes — Issues resolved in this release
• Breaking Changes — Changes that require user action or code updates
• Deprecations — Features being phased out (with timeline)
• Known Issues — Problems shipping with this release (with workarounds)

Present the categorized list for confirmation.

GATE: Confirm categorization before writing the full notes.

Phase 3: Write

Release Notes Format

# Release Notes — v[X.Y.Z]
**Release Date:** [Date]

## Highlights

[1-2 paragraph summary of the most important changes in this release. Write for someone skimming — they should understand the impact in 30 seconds.]

## New Features

- **[Feature name]** — [What it does and how to access it. 1-2 sentences.]

## Improvements

- **[Area improved]** — [What changed and the user benefit. 1 sentence.]

## Bug Fixes

- **[Issue description]** — [What was broken and confirmation it is resolved. 1 sentence.]

## Breaking Changes

### [Change title]
**Impact:** [Who is affected and how]
**Action required:** [Exactly what users must do]
**Migration guide:** [Step-by-step instructions]
**Deadline:** [When the old behavior stops working]

## Deprecations

- **[Feature name]** — Deprecated as of this release. Will be removed in v[X.Y.Z]. Use [alternative] instead.

## Known Issues

- **[Issue description]** — [Workaround if available. Expected fix in v[X.Y.Z].]

Writing Rules

• Highlights section is mandatory — even for small releases, summarize the key changes in 2-3 sentences
• User-facing language — translate technical changes to user impact
• Specific bug fix descriptions — "Fixed login failure on Safari 17" not "Fixed authentication bug"
• Breaking changes get full treatment — impact statement, action required, migration steps, and deadline
• Known issues include workarounds — never list a known issue without a workaround or expected fix date

Phase 4: Polish

1. Migration Guide (if breaking changes exist)

Write a step-by-step migration guide:

• Before/after code examples
• Configuration changes required
• Timeline for backward compatibility
• Support contact for migration issues

2. Distribution Plan

3. Quality Checklist

## Release Notes Checklist

- [ ] Version number and date are clearly stated
- [ ] Highlights section summarizes key changes in 2-3 sentences
- [ ] All changes are categorized (New, Improved, Fixed, Breaking, Deprecated)
- [ ] Breaking changes include impact, action required, and migration steps
- [ ] Bug fixes describe what was broken specifically
- [ ] Known issues include workarounds or fix timelines
- [ ] Language is understandable by non-technical users
- [ ] No internal jargon, ticket numbers, or code references in user-facing notes
- [ ] Distribution plan covers all relevant channels
- [ ] Deprecation timeline is specific (version number and date)

Example

Version: v2.4.0 Release date: February 27, 2026

Highlights excerpt: "Version 2.4.0 introduces recurring invoices and a redesigned dashboard. Recurring invoices let you schedule automatic billing on any cadence — set it once, and invoices send themselves. The new dashboard loads 60% faster and surfaces your most important metrics at a glance."

Breaking change excerpt:

### API v1 Endpoints Deprecated

**Impact:** All users making API calls to api.example.com/v1/ endpoints.
**Action required:** Update your API calls to use /v2/ endpoints by April 30, 2026.
**Migration guide:**
1. Replace /v1/ with /v2/ in all endpoint URLs
2. Update the Authorization header format (see docs)
3. Test with the sandbox environment
4. Switch production calls before April 30

**Deadline:** April 30, 2026. After this date, /v1/ endpoints will return 410 Gone.

Anti-Patterns

• Dumping git commit messages — "Fixed #4521" and "Refactored user service" are not release notes. Translate to user impact.
• Hiding breaking changes — burying them at the bottom guarantees angry users. Lead with breaking changes or highlight them prominently.
• No migration guide — telling users something broke without telling them how to fix it is worse than not telling them at all.
• Skipping known issues — users will find them anyway. Documenting them proactively builds trust.
• Marketing fluff — release notes are not blog posts. Be factual, specific, and concise.

Recovery

• Tiny release with few changes: Write a brief note. Even "Bug fixes and performance improvements" is better than silence, but add specifics.
• Major breaking change with complex migration: Create a dedicated migration guide document. Link from the release notes.
• Known issue with no workaround: State the issue, acknowledge the impact, and provide a timeline for the fix. Offer direct support contact.
• Release was rolled back: Publish a note explaining the rollback, what was affected, and when the re-release is expected.