release-notes-generator

# Release Notes Generator

## Overview

Transform engineering commit logs into customer-friendly updates that drive adoption and demonstrate value. This skill encodes the frameworks for writing release notes that different audiences actually read.

## Release Note Structure

### Standard Format

```
[VERSION] - [DATE]

🚀 NEW
- [Feature]: [User benefit] [Link to docs]

✨ IMPROVED  
- [Enhancement]: [What's better]

🐛 FIXED
- [Bug]: [What was wrong, now resolved]

⚠️ CHANGED
- [Breaking change]: [What to do]

📚 DOCUMENTATION
- [Doc update]: [What's new]
```

## Audience-Specific Versions

### End User (Customer-Facing)

**Tone:** Benefit-focused, simple language
**Length:** 3-5 bullets per category

**Example:**
> **New: Export to Excel**
> You can now export any report to Excel with one click. Find the export button in the top right of any report view.

### Technical (Developer-Facing)

**Tone:** Precise, technical detail
**Include:** API changes, breaking changes, migration steps

**Example:**
> **API: New pagination parameters**
> Added `cursor` and `limit` parameters to `/api/v2/users`. The `offset` parameter is deprecated and will be removed in v3.0. See [migration guide].

### Internal (Sales/CS)

**Tone:** Enablement-focused
**Include:** Talking points, competitive implications

**Example:**
> **New: Export to Excel**
> - Talking point: "You can now export any report to Excel instantly"
> - Customer ask this solves: Export functionality (requested by 47 customers)
> - Competitive note: Competitor X charges extra for this

## Categorization Framework

| Category | Icon | Include When |
|----------|------|--------------|
| New | 🚀 | New features or capabilities |
| Improved | ✨ | Enhancements to existing features |
| Fixed | 🐛 | Bug fixes |
| Changed | ⚠️ | Breaking changes, deprecations |
| Security | 🔒 | Security updates |
| Performance | ⚡ | Speed/efficiency improvements |

## Writing Guidelines

### Transform Technical to User

| Technical | User-Friendly |
|-----------|---------------|
| "Implemented caching layer" | "Reports now load 3x faster" |
| "Fixed null pointer exception" | "Resolved issue causing occasional crashes" |
| "Added OAuth2 support" | "You can now sign in with Google" |
| "Refactored data model" | [Don't include - no user impact] |

### What to Include/Exclude

**Include:**
- User-facing changes
- Performance improvements users will notice
- Bug fixes users reported
- Security updates

**Exclude:**
- Internal refactoring
- Test improvements
- Dependency updates (unless security)
- Changes with no user impact

## Changelog Format (Technical)

```markdown
## [1.2.0] - 2025-01-15

### Added
- New `export` endpoint for bulk data retrieval (#234)
- Support for custom date formats in reports (#256)

### Changed
- `GET /users` now requires pagination (breaking) (#289)
- Minimum API version bumped to 2.0 (#290)

### Deprecated
- `offset` parameter on list endpoints (#289)

### Fixed
- Race condition in concurrent webhook delivery (#245)
- Incorrect timezone handling in scheduled reports (#267)

### Security
- Patched XSS vulnerability in comment rendering (#278)
```

## Multi-Channel Adaptation

| Channel | Format | Length |
|---------|--------|--------|
| In-app | Modal or banner | 2-3 key items |
| Email | HTML newsletter | Full release notes |
| Blog | Narrative post | Feature spotlight + notes |
| Docs | Changelog page | Complete technical log |
| Social | Tweet/post | 1 highlight + link |
| Slack | Notification | Summary + link |

## Resources

### references/
- **changelog-standards.md** — Keep a Changelog format guide

### assets/
- **release-email-template.html** — Email newsletter template