Release Notes

---

name: release-notes description: Transform technical changelogs and tickets into user-facing release notes written in benefit language. Use when shipping a release, communicating product updates, or preparing changelog communications. tags: [release-notes, communication, changelog, product-updates]

Release Notes

Transform technical changelogs, PRs, and tickets into clear, user-facing release notes that communicate what changed and why it matters — in language customers understand.

---

Purpose

Technical changelogs are written for developers. Release notes are written for customers. This skill bridges the gap — translating implementation details into benefit-oriented language that helps users understand, adopt, and appreciate product improvements.

---

When to Use

• After merging a release branch and preparing for deployment
• Weekly or bi-weekly product update communications
• Monthly product newsletters
• App store update descriptions
• In-app "What's New" notifications

When NOT to Use

• Internal engineering changelogs (keep those technical)
• Security advisories (use a dedicated security disclosure format)
• API breaking change notices (use migration guides)

---

Required Input

Provide any combination of:

• Git log / PR list for the release
• Completed JIRA/Linear tickets
• Sprint review notes
• PRD sections for shipped features
• Technical changelogs

---

The Process

Step 1: Categorize Changes

Sort every change into one of these categories:

Category	Icon	Description
New Features	New	Entirely new capabilities
Improvements	Improved	Enhancements to existing features
Bug Fixes	Fixed	Issues that are now resolved
Breaking Changes	Breaking	Changes that require user action
Deprecations	Deprecated	Features being removed in a future release

Step 2: Rewrite in Benefit Language

Transform each change from technical to user-facing:

Rules:

• Lead with the benefit, not the implementation
• Use plain language — no jargon, no ticket numbers, no internal terms
• Keep each entry to 1–3 sentences
• Be specific about the improvement (quantify when possible)

Examples:

Technical (Before)	User-Facing (After)
Implemented Redis caching for dashboard queries	Dashboards now load up to 3x faster
Fixed null pointer exception in report export	Report exports no longer fail for accounts with empty custom fields
Added SAML SSO support (SCIM provisioning)	Enterprise teams can now sign in with their company SSO — no more separate passwords
Migrated search to Elasticsearch	Search results are now more accurate and return in under 200ms
Refactored payment processing module	(Omit — internal refactoring with no user-visible change)
Updated React from v17 to v18	(Omit — unless there's a user-visible improvement)

Step 3: Determine Tone

Adjust tone based on audience:

Audience	Tone	Example
B2B Professional	Clear, confident, concise	"Dashboards now load up to 3x faster."
Consumer / Friendly	Warm, conversational, excited	"Your dashboards just got a speed boost — they load 3x faster now!"
Developer / API	Technical, precise, actionable	"Dashboard API response times reduced from ~900ms to ~300ms via query caching."

Step 4: Structure the Release Notes

---

Output Format

# Release Notes — [Version or Date]

**Released:** [date]

---

## New Features

### [Feature Name]
[1-3 sentences describing what it does and why it matters to the user]

### [Feature Name]
[description]

---

## Improvements

- **[Area]** — [What improved and the benefit]
- **[Area]** — [What improved and the benefit]

---

## Bug Fixes

- Fixed an issue where [user-visible problem] — [what works now]
- Fixed an issue where [user-visible problem] — [what works now]

---

## Breaking Changes

### [Change Description]
**What changed:** [specific change]
**What you need to do:** [clear migration steps]
**Deadline:** [if applicable]

---

## Deprecations

- **[Feature/API]** will be removed on [date]. [Migration path or alternative].

---

Filtering Rules

Include:

• Any change that affects what users see, do, or experience
• Performance improvements users would notice
• Bug fixes for reported issues
• Security improvements (without disclosing vulnerability details)

Exclude:

• Internal refactoring with no user-visible impact
• Dependency updates (unless they fix a user-visible issue)
• Build system or CI/CD changes
• Test additions or modifications
• Code style or formatting changes

---

Distribution Channels

Adapt the release notes for each channel:

Channel	Format	Length
In-app notification	1–3 bullet highlights	Very short
Email newsletter	Full release notes with context	Medium
Blog post	Narrative with screenshots	Long
App store description	Top 3 changes in bullet form	Very short
Changelog page	Full structured notes	Medium
Slack/Discord	Emoji-formatted highlights	Short
API docs	Technical details + migration guides	Technical

---

Anti-Patterns

Avoid	Why	Instead
Ticket numbers in notes	Customers don't know what PROJ-1234 means	Describe the change in plain language
"Various bug fixes"	Dismissive, unhelpful, erodes trust	List specific fixes or say "stability improvements including [example]"
Technical jargon	"Optimized SQL query" means nothing to users	"Reports now load faster"
Listing internal refactors	Adds noise, no user value	Only include user-visible changes
No categorization	Hard to scan, important changes get buried	Use consistent categories
Stale release notes	Notes published days/weeks after release	Ship notes with the release

---

References

• Keep a Changelog
• Slite: How to Write Release Notes