changelog

What this skill does

# Changelog Skill

When generating a changelog, follow this structured process. Good release notes tell users and developers what changed, why it matters, and what they need to do about it.

## 1. Discovery — Understand the Release Context

### Detect Versioning Strategy
```bash
# Check for existing changelog
cat CHANGELOG.md CHANGELOG CHANGES.md HISTORY.md RELEASE_NOTES.md 2>/dev/null | head -30

# Check package version
cat package.json 2>/dev/null | grep '"version"'
cat pyproject.toml 2>/dev/null | grep 'version'
cat Cargo.toml 2>/dev/null | grep '^version'
cat pom.xml 2>/dev/null | grep -m1 '<version>'
cat build.gradle 2>/dev/null | grep 'version'
cat mix.exs 2>/dev/null | grep '@version'
cat setup.py 2>/dev/null | grep 'version'
cat composer.json 2>/dev/null | grep '"version"'
cat *.gemspec 2>/dev/null | grep 'version'

# List existing tags
git tag --sort=-version:refname | head -20

# Latest tag
git describe --tags --abbrev=0 2>/dev/null

# Check for release branches
git branch -r | grep -E "release/|v[0-9]"
```

### Determine Range
```bash
# Commits since last tag
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)
echo "Last tag: $LAST_TAG"

# If no tags, use initial commit
if [ -z "$LAST_TAG" ]; then
  LAST_TAG=$(git rev-list --max-parents=0 HEAD)
  echo "No tags found, using first commit: $LAST_TAG"
fi

# Commit count since last tag
git rev-list --count ${LAST_TAG}..HEAD

# Date range
echo "From: $(git log -1 --format=%ci $LAST_TAG)"
echo "To: $(git log -1 --format=%ci HEAD)"
```

## 2. Gather Changes

### Collect Commits
```bash
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)

# All commits since last tag with full message
git log ${LAST_TAG}..HEAD --format="COMMIT_START%nHash: %H%nShort: %h%nAuthor: %aN <%aE>%nDate: %ai%nSubject: %s%nBody: %b%nCOMMIT_END"

# One-line summary
git log ${LAST_TAG}..HEAD --oneline

# With file changes
git log ${LAST_TAG}..HEAD --oneline --name-status

# Diff stats
git diff --stat ${LAST_TAG}..HEAD

# Contributors
git log ${LAST_TAG}..HEAD --format='%aN' | sort | uniq -c | sort -rn
```

### Collect Merged PRs (GitHub)
```bash
# List merged PRs since last tag date
LAST_TAG_DATE=$(git log -1 --format=%ci $(git describe --tags --abbrev=0 2>/dev/null) 2>/dev/null)

# Using gh CLI
gh pr list --state merged --search "merged:>=${LAST_TAG_DATE}" --json number,title,labels,author,body --limit 100

# Alternative: extract PR numbers from merge commits
git log ${LAST_TAG}..HEAD --oneline --grep="Merge pull request" | grep -oE "#[0-9]+"
git log ${LAST_TAG}..HEAD --oneline --grep="(#[0-9]+)" | grep -oE "#[0-9]+"
```

### Collect Merged MRs (GitLab)
```bash
# Using glab CLI
glab mr list --state merged --json number,title,labels,author
```

## 3. Categorize Changes

### Parse Conventional Commits

Classify commits based on their prefix:

| Prefix | Category | User-Facing Label |
|--------|----------|-------------------|
| `feat:` / `feature:` | Features | ✨ New Features |
| `fix:` / `bugfix:` | Bug Fixes | 🐛 Bug Fixes |
| `perf:` | Performance | ⚡ Performance Improvements |
| `security:` | Security | 🔒 Security |
| `breaking:` / `BREAKING CHANGE:` | Breaking | 💥 Breaking Changes |
| `refactor:` | Refactoring | ♻️ Refactoring |
| `docs:` | Documentation | 📝 Documentation |
| `test:` | Testing | ✅ Testing |
| `chore:` | Maintenance | 🔧 Maintenance |
| `ci:` | CI/CD | 🏗️ CI/CD |
| `style:` | Code Style | 💄 Code Style |
| `deps:` / `build:` | Dependencies | 📦 Dependencies |
| `revert:` | Reverts | ⏪ Reverts |
| `deprecate:` | Deprecations | ⚠️ Deprecations |

### If Commits Are NOT Conventional

When commits don't follow conventional format, analyze the diff to categorize:
```bash
# Analyze what areas changed
git diff --stat ${LAST_TAG}..HEAD | tail -1  # summary

# Group by directory/module
git diff --name-only ${LAST_TAG}..HEAD | sed 's|/.*||' | sort | uniq -c | sort -rn

# Look for keywords in commit messages
git log ${LAST_TAG}..HEAD --oneline | grep -iE "fix|bug|patch|resolve" # Bug fixes
git log ${LAST_TAG}..HEAD --oneline | grep -iE "add|new|feature|implement|support" # Features
git log ${LAST_TAG}..HEAD --oneline | grep -iE "remove|delete|deprecate|drop" # Removals
git log ${LAST_TAG}..HEAD --oneline | grep -iE "update|upgrade|bump|depend" # Dependencies
git log ${LAST_TAG}..HEAD --oneline | grep -iE "perf|speed|fast|optim|cache" # Performance
git log ${LAST_TAG}..HEAD --oneline | grep -iE "security|vuln|cve|auth" # Security
git log ${LAST_TAG}..HEAD --oneline | grep -iE "refactor|clean|restructure" # Refactoring
git log ${LAST_TAG}..HEAD --oneline | grep -iE "doc|readme|comment" # Docs
git log ${LAST_TAG}..HEAD --oneline | grep -iE "test|spec|coverage" # Testing
git log ${LAST_TAG}..HEAD --oneline | grep -iE "ci|pipeline|workflow|deploy" # CI/CD
```

### Detect Breaking Changes
```bash
# Check commit bodies for BREAKING CHANGE
git log ${LAST_TAG}..HEAD --format="%B" | grep -i "BREAKING CHANGE"

# Check for removed exports/endpoints
git diff ${LAST_TAG}..HEAD -- "*.ts" "*.js" | grep -E "^-export|^-module\.exports"
git diff ${LAST_TAG}..HEAD -- "*.py" | grep -E "^-def |^-class "

# Check for removed API routes
git diff ${LAST_TAG}..HEAD -- "*route*" "*controller*" "*endpoint*" | grep "^-"

# Check for database migrations that drop/rename
find . -name "*.sql" -newer $(git rev-parse ${LAST_TAG}) | xargs grep -liE "DROP|RENAME|ALTER.*DROP" 2>/dev/null

# Check for changed config/env requirements
git diff ${LAST_TAG}..HEAD -- ".env.example" "*.config.*" "docker-compose.*"
```

## 4. Changelog Formats

### Format A: Keep a Changelog (Recommended for Libraries/OSS)

Follows [keepachangelog.com](https://keepachangelog.com) format:
```markdown
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [2.4.0] - 2026-02-17

### Added
- OAuth2 login support with Google and GitHub providers (#234)
- Real-time order status notifications via WebSocket (#241)
- Bulk export of analytics data in CSV and JSON formats (#238)
- Rate limiting on all public API endpoints (#245)

### Changed
- Upgraded Next.js from 14.2 to 15.1 (#250)
- Migrated email service from Mailgun to SendGrid (#247)
- Improved search indexing performance by 3x with batch processing (#243)

### Fixed
- Fixed duplicate charge on payment retry when Stripe webhook is delayed (#236)
- Fixed pagination returning wrong total count on filtered queries (#239)
- Fixed timezone handling in scheduled report generation (#242)
- Fixed memory leak in WebSocket connection handler (#248)

### Security
- Patched XSS vulnerability in user profile bio field (#237)
- Updated jsonwebtoken to 9.0.2 to fix CVE-2024-XXXXX (#246)

### Deprecated
- The `/api/v1/reports` endpoint is deprecated in favor of `/api/v2/analytics`. Will be removed in v3.0.0.

### Removed
- Removed legacy CSV import endpoint `/api/v1/import/csv` (use `/api/v2/import` instead)

## [2.3.1] - 2026-01-28

### Fixed
- ...

[Unreleased]: https://github.com/org/repo/compare/v2.4.0...HEAD
[2.4.0]: https://github.com/org/repo/compare/v2.3.1...v2.4.0
[2.3.1]: https://github.com/org/repo/compare/v2.3.0...v2.3.1
```

### Format B: User-Facing Release Notes (For Products/Apps)

Written for end users, not developers:
```markdown
# What's New in v2.4.0 🚀

Released: February 17, 2026

## Highlights

### Sign in with Google and GitHub
You can now log in using your Google or GitHub account — no more passwords
to remember. Head to Settings → Account → Connected Accounts to link yours.

### Live Order Tracking
Watch your order status update in real time. No more refreshing the page —
you'll see status changes the moment they happen.

### Bulk Data Export
Export your analytics data in CSV or JSON format. Perfect for custom reports
or importing into your own tools. Find it under Analytics → Export.

## Improveme