Release Notes

Release Notes Expert

Overview

Transform raw technical changes -- tickets, changelogs, git logs, PRDs -- into clear, user-benefit-oriented release notes. This skill ensures every release communicates value to the right audience in the right tone.

When to Use

• Product Releases -- Announcing new versions to customers, partners, or internal stakeholders.
• Sprint Demos -- Summarizing what shipped for sprint review audiences.
• Changelog Maintenance -- Keeping a running log of changes across releases.
• Customer Communication -- Preparing release announcements for email, in-app, or documentation.

Methodology

Step 1: Gather Raw Input

Collect all changes from the release cycle:

• Jira/Linear tickets -- Completed stories, bugs, and tasks
• Git log -- Merge commits since last release tag
• PRD references -- Feature specs that shipped
• Hotfix records -- Emergency fixes deployed between releases

Step 2: Classify Each Change

Assign every change to exactly one category:

Classification rules:

• If a change adds something entirely new, it is a New Feature.
• If it makes something existing better (faster, easier, more reliable), it is an Improvement.
• If it fixes something that was wrong, it is a Bug Fix.
• If users must change their behavior, configuration, or integration, it is a Breaking Change.
• If a feature still works but will be removed later, it is a Deprecation.

Step 3: Rewrite for User Benefit

The most critical step. Every entry must lead with the benefit to the user, not the technical change.

Rewriting principles:

1. Lead with the outcome. What can the user do now that they could not before, or what is better for them? 2. Use plain language. Avoid internal jargon, code references, or implementation details. 3. Keep it to 1-3 sentences. One sentence for minor items, up to three for significant features. 4. Include context when needed. If users need to take action, tell them exactly what to do.

Before and after examples:

Red flags that an entry needs rewriting:

• Mentions a class name, function, or library
• Starts with "Refactored," "Migrated," or "Updated" without stating impact
• Uses acronyms the target audience would not know
• Describes what the team did instead of what the user gains

Step 4: Adjust Tone for Audience

Step 5: Assemble the Release Notes

Use the output template below. Include only categories that have entries -- do not show empty sections.

Output Template

# [Product Name] v[X.Y.Z] Release Notes

**Release Date:** [YYYY-MM-DD]

---

## New Features

- **[Feature Name]** -- [1-3 sentence description of user benefit]. ([TICKET-ID])

## Improvements

- **[Improvement Name]** -- [1-2 sentence description of what is better]. ([TICKET-ID])

## Bug Fixes

- **[Bug Fix Name]** -- [1 sentence describing what was broken and that it is now fixed]. ([TICKET-ID])

## Breaking Changes

> **Action Required:** The following changes require updates on your end.

- **[Change Name]** -- [Description of what changed and exactly what the user must do]. ([TICKET-ID])

## Deprecations

> **Planned Removal:** The following features will be removed in a future release.

- **[Feature Name]** -- [What is being deprecated and when it will be removed. Recommend alternative if available]. ([TICKET-ID])

---

**Full changelog:** [link]
**Questions?** [support link or contact]

Python Tool

Use scripts/release_notes_generator.py to generate formatted release notes from structured input.

# Generate from JSON input
python scripts/release_notes_generator.py --input changes.json --product-name "Acme App" --version "2.5.0"

# Run with demo data
python scripts/release_notes_generator.py --demo --product-name "Acme App" --version "1.0.0"

# Output as JSON instead of markdown
python scripts/release_notes_generator.py --input changes.json --format json --product-name "Acme App" --version "2.5.0"

See scripts/release_notes_generator.py --help for full usage.

Integration with Other Skills

• Use summarize-meeting/ to capture release planning discussions.
• Use job-stories/ or wwas/ to trace features back to their original motivation.
• Pair with ../senior-pm/ for stakeholder communication planning around major releases.

Troubleshooting

Success Criteria

• Every release has structured notes published within 24 hours of deployment
• All entries lead with user benefit, not technical implementation details
• Breaking changes include explicit migration instructions with deadlines
• Deprecations include removal timeline and recommended alternatives
• Technical language flags reviewed and addressed before publication
• Release notes tone matches the target audience (B2B/consumer/developer/internal)
• Entries traceable to tickets via ticket_id for audit and context

Scope & Limitations

In Scope:

• Structured release note generation from JSON input with 5 entry categories
• Automatic technical language detection with rewriting suggestions
• Markdown and JSON output formatting with category grouping
• Audience tone guidance (B2B, consumer, developer, internal)
• Classification rules for New Features, Improvements, Bug Fixes, Breaking Changes, and Deprecations

Out of Scope:

• Automatic extraction of changes from git history (see sprint-retrospective/ for git analysis)
• Jira/Linear ticket integration for pulling completed stories (manual JSON input required)
• Changelog maintenance across multiple releases (this tool generates per-release notes)
• Distribution to email, in-app, or documentation channels (output is markdown/JSON for further processing)

Important Caveats:

• The rewriting suggestions are pattern-based heuristics. They catch common technical language but cannot assess whether a description truly communicates user benefit.
• Semantic versioning alignment is the user's responsibility. The tool does not validate that version numbers follow semver conventions relative to the change types present.
• Breaking changes require special care. Always include: what changed, what the user must do, and by when. Vague breaking change notes erode user trust.

Integration Points

Tool Reference

release_notes_generator.py

Generates formatted release notes from structured JSON input. Groups entries by category, formats into markdown or JSON, and flags entries that may need user-benefit rewriting.

Input JSON schema:

{
  "entries": [
    {
      "title": "Feature Name",
      "description": "User-benefit description (1-3 sentences)",
      "type": "feature|improvement|bugfix|breaking|deprecation",
      "ticket_id": "PROJ-123 (optional)"
    }
  ]
}

References

• See references/release-notes-guide.md for best practices, audience guidance, and examples.
• See assets/release_notes_template.md for a ready-to-use document template.

[Product Name] v[X.Y.Z] Release Notes

Release Date: [YYYY-MM-DD]

---

New Features

• [Feature Name] -- [1-3 sentence description of user benefit. What can the user do now that they could not before?] ([TICKET-ID])

Improvements

• [Improvement Name] -- [1-2 sentence description of what is better. Quantify the improvement when possible.] ([TICKET-ID])

Bug Fixes

• [Bug Fix Name] -- [1 sentence describing what was broken and that it is now fixed.] ([TICKET-ID])

Breaking Changes

Action Required: The following changes require updates on your end.

• [Change Name] -- [Description of what changed and exactly what the user must do. Include a deadline if applicable.] ([TICKET-ID])

Deprecations

Planned Removal: The following features will be removed in a future release.

• [Feature Name] -- [What is being deprecated, when it will be removed, and what to use instead.] ([TICKET-ID])

---

Full changelog: [link to changelog or diff] Migration guide: [link, if breaking changes exist] Questions? [support link or contact]

---

Entry Template

Use this template for each individual entry before adding it to the release notes:

Release Notes Best Practices Guide

Purpose

Release notes are the bridge between what your team built and what your users understand. They serve three functions: inform users of what changed, build trust through transparency, and drive adoption of new capabilities.

Category Definitions

New Features

Something that did not exist before. The user gains a capability they previously lacked.

Test: Could the user do this yesterday? If no, it is a new feature.

Improvements

An existing capability that is now better -- faster, easier, more reliable, more accessible.

Test: Could the user already do this, but now it is better? If yes, it is an improvement.

Bug Fixes

Something was broken and is now fixed. The software was not behaving as intended or documented.

Test: Was this a defect report or unexpected behavior? If yes, it is a bug fix.

Breaking Changes

A change that requires the user to take action. Their existing workflow, integration, or configuration will stop working or behave differently without intervention.

Test: Will anything break for the user if they do nothing? If yes, it is a breaking change.

Deprecations

A feature that still works today but will be removed in a future release. This gives users time to migrate.

Test: Does it still work but is scheduled for removal? If yes, it is a deprecation.

Writing for Different Audiences

B2B / Enterprise

• Tone: Professional, precise, confident
• Emphasize: Reliability, security, compliance, productivity gains
• Avoid: Casual language, exclamation marks, emojis
• Include: Impact on workflows, admin actions required, compliance implications
• Example: "Role-based access controls now support custom permission sets, enabling administrators to define granular access policies aligned with organizational security requirements."

Consumer

• Tone: Friendly, conversational, enthusiastic (measured)
• Emphasize: Ease of use, delight, time saved, new possibilities
• Avoid: Technical jargon, implementation details
• Include: Visual descriptions, tips for getting started
• Example: "You can now organize your photos into custom albums. Tap the new Albums tab to get started."

Developer / API

• Tone: Technical, direct, specific
• Emphasize: Endpoints, parameters, SDK versions, migration steps
• Avoid: Marketing language, vague descriptions
• Include: Code snippets, request/response examples, version numbers
• Example: "The GET /v2/users endpoint now accepts an optional fields query parameter for sparse fieldsets. See the API reference for supported field names."

Internal Stakeholders

• Tone: Detailed, context-rich
• Emphasize: Business impact, metrics, team contributions
• Avoid: Over-simplification
• Include: Ticket IDs, team names, technical context as needed

Distribution Channels

Good vs Bad Examples

Bad: Technical and self-centered

- Updated React from v17 to v18

- Refactored UserService to use repository pattern

- Fixed NPE in ReportExportHandler.java line 234

- Migrated auth to PKCE flow

Good: User-benefit-oriented

- Smoother interactions -- Page transitions and form updates are now noticeably faster and more responsive.

- Faster report exports -- Reports that previously timed out now complete reliably, even for large date ranges.

- More secure sign-in -- Your account is now protected by an upgraded authentication standard that works consistently across all browsers.

Bad: Vague and unhelpful

- Various bug fixes and improvements

- Performance enhancements

- Updated dependencies

Good: Specific and actionable

- Fixed: CSV exports now include all columns when custom fields are enabled. (BUG-3421)

- Faster: Dashboard widgets load 40% faster on pages with more than 20 widgets.

- Updated: The Python SDK now requires Python 3.9 or later. See the migration guide for upgrade instructions.

Checklist Before Publishing

• [ ] Every entry leads with user benefit, not technical change
• [ ] No internal jargon, class names, or function references
• [ ] Breaking changes clearly state what the user must do
• [ ] Deprecations include a timeline and recommended alternative
• [ ] Tone matches the target audience
• [ ] Ticket IDs are included for traceability (if appropriate for audience)
• [ ] Empty categories are removed
• [ ] Release date and version number are correct
• [ ] Links to full changelog, support, and migration guides are included