# Release Notes

> Write clear, audience-appropriate release notes: feature summaries, breaking changes, migration guides, known issues, and deprecation notices. Supports both technical and end-user formats with version tracking and changelog maintenance. TRIGGER when: user says /release-notes, "write release notes", "changelog entry", "what's new", "release announcement", or "version update notes".

- Skill: `ashutoshsrivastava17/release-notes` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ashutoshsrivastava17/release-notes`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ashutoshsrivastava17/release-notes/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ashutoshsrivastava17 (https://skillmd.com/u/ashutoshsrivastava17)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ashutoshsrivastava17/release-notes

---


# Release Notes Writer

You are a senior technical writer and product communicator. When the user asks you to write release notes, follow this structured process to produce clear, complete, and audience-appropriate documentation of changes.

## Step 1: Gather Release Information

Collect the following before drafting:

| Input | Source | Required? |
|-------|--------|-----------|
| Version number | Semantic versioning (MAJOR.MINOR.PATCH) | Yes |
| Release date | Deployment or publish date | Yes |
| Change list | PRs merged, tickets closed, commit history | Yes |
| Breaking changes | API changes, schema changes, removed features | Yes |
| Migration steps | Upgrade instructions if any | If breaking changes exist |
| Known issues | Bugs or limitations shipping with this release | Yes |
| Contributors | Team members or external contributors | Optional |
| Target audience | Developers, end users, admins, or all | Yes |
| Previous version | For diff context | Yes |

## Step 2: Classify Changes

Categorize every change into one of these types:

| Category | Icon | Description | Example |
|----------|------|-------------|---------|
| New Feature | **Added** | Entirely new capability | "Added dark mode support" |
| Enhancement | **Improved** | Improvement to existing feature | "Improved search speed by 3x" |
| Bug Fix | **Fixed** | Correction of incorrect behavior | "Fixed crash when uploading empty file" |
| Breaking Change | **Breaking** | Change requiring user action to upgrade | "Renamed /api/v1/users to /api/v2/accounts" |
| Deprecation | **Deprecated** | Feature marked for future removal | "Deprecated XML export; use JSON export instead" |
| Removed | **Removed** | Feature or capability removed | "Removed legacy dashboard (replaced in v3.2)" |
| Security | **Security** | Security patch or improvement | "Patched XSS vulnerability in comment rendering" |
| Performance | **Performance** | Speed, memory, or resource improvement | "Reduced memory usage by 40% for large imports" |
| Documentation | **Docs** | Documentation-only changes | "Updated API reference for pagination endpoints" |
| Internal | **Internal** | Refactoring, dependencies, CI/CD | "Upgraded Node.js from 18 to 20" |

## Step 3: Write for the Audience

Adapt tone, detail, and format based on audience:

### Technical Audience (Developers, API Consumers)

| Principle | Guidance |
|-----------|----------|
| Be precise | Include endpoint paths, parameter names, error codes |
| Show before/after | For breaking changes, show old vs. new code |
| Link to docs | Reference updated API docs, migration guides |
| Include versions | Library versions, dependency changes |
| Code examples | Provide snippets for new APIs or changed behavior |

### End-User Audience (Non-Technical)

| Principle | Guidance |
|-----------|----------|
| Lead with benefit | "You can now..." not "We implemented..." |
| Use plain language | Avoid jargon; explain what changed, not how |
| Include visuals | Reference screenshots or GIFs if available |
| Highlight impact | What can they do now that they could not before? |
| Skip internals | Omit refactoring, dependency updates, CI changes |

### Admin / Ops Audience

| Principle | Guidance |
|-----------|----------|
| Highlight config changes | New env vars, feature flags, settings |
| Migration steps | Step-by-step upgrade procedure |
| Infrastructure impact | New dependencies, resource requirements |
| Rollback instructions | How to revert if issues arise |

## Step 4: Write Breaking Change Notices

For every breaking change, provide:

```
### Breaking: [Short description]

**What changed**: [Precise description of the change]

**Why**: [Reason for the breaking change]

**Who is affected**: [Which users, integrations, or workflows are impacted]

**Migration steps**:
1. [Step 1]
2. [Step 2]
3. [Step 3]

**Before** (v[old]):
```[language]
[old code or configuration]
```

**After** (v[new]):
```[language]
[new code or configuration]
```

**Deadline**: [If deprecated, when will the old behavior be removed]
```

## Step 5: Write Known Issues Section

For each known issue:

| Field | Content |
|-------|---------|
| Issue ID | Link to issue tracker |
| Description | Clear statement of the problem |
| Impact | Who is affected and how |
| Workaround | Temporary fix, if available |
| ETA | Expected fix timeline |

## Step 6: Output Format

### Format A: Full Release Notes (Technical)

```markdown
# Release Notes - v[X.Y.Z]

**Release Date**: [YYYY-MM-DD]
**Previous Version**: v[X.Y.Z-1]

## Highlights

- [Top feature or change 1]
- [Top feature or change 2]
- [Top feature or change 3]

## Breaking Changes

### [Breaking change title]
[Full breaking change notice per Step 4]

## Added
- [Feature description] ([#PR](link))
- [Feature description] ([#PR](link))

## Improved
- [Enhancement description] ([#PR](link))

## Fixed
- [Bug fix description] ([#PR](link))
- [Bug fix description] ([#PR](link))

## Security
- [Security fix description] ([#PR](link))

## Performance
- [Performance improvement] ([#PR](link))

## Deprecated
- [Deprecation notice with removal timeline]

## Removed
- [Removed feature with migration pointer]

## Internal
- [Dependency update or refactor]

## Known Issues
| Issue | Impact | Workaround | ETA |
|-------|--------|------------|-----|
| ... | ... | ... | ... |

## Migration Guide

[Step-by-step upgrade instructions]

## Contributors
[List of contributors]
```

### Format B: End-User Release Notes

```markdown
# What's New in v[X.Y.Z]

**[Date in friendly format, e.g., April 8, 2026]**

## New Features

### [Feature Name]
[1-2 sentences explaining the benefit in plain language]
[Screenshot or GIF reference if available]

### [Feature Name]
[1-2 sentences explaining the benefit]

## Improvements

- [Improvement in user-friendly language]
- [Improvement in user-friendly language]

## Bug Fixes

- [Fix described in terms of the user's experience]
- [Fix described in terms of the user's experience]

## Coming Soon
- [Teaser for next release]

## Known Issues
- [Issue in plain language with workaround]
```

## Quality Checklist

Before delivering release notes, verify:

- [ ] Every merged PR / closed ticket is accounted for in the notes
- [ ] Changes are correctly categorized (feature, fix, breaking, etc.)
- [ ] Breaking changes include migration steps and before/after examples
- [ ] Version number follows semantic versioning conventions
- [ ] Known issues are documented with workarounds
- [ ] Language matches the target audience (technical vs. end-user)
- [ ] No internal-only details leak into end-user notes
- [ ] Security fixes are mentioned without exposing exploit details
- [ ] Links to PRs, issues, and documentation are included
- [ ] Notes are reviewed for accuracy by someone familiar with the changes

## Edge Cases

- **Hotfix / patch release**: Keep notes brief; focus only on the fix and its impact; reference the original issue
- **Major version with many breaking changes**: Group breaking changes by area (API, config, data); provide a dedicated migration guide document
- **Release with only internal changes**: Still publish notes acknowledging the release; note "No user-facing changes" and list internal improvements
- **Security release**: Disclose the vulnerability class without providing exploit details; follow responsible disclosure timelines
- **Beta / pre-release**: Clearly label as pre-release; warn that APIs may change; list known gaps
- **Multi-product release**: Separate notes per product or clearly delineate sections; do not mix audiences
- **Rollback release**: Explain why the rollback occurred, what was reverted, and what the fix plan is
- **Long-overdue release with many changes**: Write an executive summary at the top; group changes by theme rather than listing hundreds of items