Release Notes Writer
Overview
Generate polished, user-facing release notes from git history, pull requests, and code changes, automatically categorizing and summarizing changes in a clear, accessible format.
Workflow
1. Gather Release Information
Collect the scope and sources for the release notes:
Define the release scope:
- What version is being released? (e.g., v2.1.0)
- What's the version range? (e.g., v2.0.0 to v2.1.0)
- Which commits/PRs should be included?
- Is this a major, minor, or patch release?
Quick commands to get started:
# Get commits since last tag
git log $(git describe --tags --abbrev=0)..HEAD --oneline
# Get commits between two tags
git log v2.0.0..v2.1.0 --oneline
# Get commits since specific date
git log --since="2024-01-01" --oneline
# List all tags
git tag -l
# Get merged PRs (if using GitHub)
gh pr list --state merged --limit 50
2. Extract Change Information
Gather details from available sources:
From Git Commits
# Get commit messages with details
git log v2.0.0..v2.1.0 --pretty=format:"%h - %s (%an)" --no-merges
# Get commits by author
git log v2.0.0..v2.1.0 --author="AuthorName" --oneline
# Get commit messages with full body
git log v2.0.0..v2.1.0 --format="%h %s%n%b%n"
Parse commit message conventions:
feat:orfeature:→ New Featurefix:orbugfix:→ Bug Fixperf:orperformance:→ Performance Improvementdocs:ordoc:→ Documentationrefactor:→ Code Quality/Refactoringtest:→ Testingchore:→ Internal/MaintenanceBREAKING:or!:→ Breaking Change
From Pull Requests
If using GitHub CLI:
# Get merged PRs
gh pr list --state merged --limit 100 --json number,title,body,labels,mergedAt
# Get PR details
gh pr view <PR-NUMBER>
Extract from PR:
- Title (often more user-friendly than commit message)
- Description (may contain user-facing summary)
- Labels (feature, bug, breaking-change, etc.)
- Linked issues
From Changelog Files
Check for existing changelog entries:
# Look for changelog files
find . -name "CHANGELOG.md" -o -name "HISTORY.md" -o -name "RELEASES.md"
# Check for unreleased section
grep -A 20 "Unreleased" CHANGELOG.md
From Code Diffs
Infer changes from code when commits lack detail:
# See what files changed
git diff --stat v2.0.0..v2.1.0
# See what functions/classes were added
git diff v2.0.0..v2.1.0 --unified=0 | grep "^+def\|^+class"
# See API changes
git diff v2.0.0..v2.1.0 -- "*.py" | grep -E "^[+-]def |^[+-]class "
3. Categorize Changes
Organize changes into standard categories:
Category: ✨ New Features
User-visible new capabilities:
- New API endpoints
- New UI components
- New configuration options
- New supported platforms
- New integrations
Examples:
- "Added dark mode support"
- "Introduced batch processing for large datasets"
Category: 🐛 Bug Fixes
Corrections to existing functionality:
- Fixed crashes or errors
- Corrected unexpected behavior
- Resolved data inconsistencies
- Fixed security vulnerabilities
Category: 🚀 Improvements
Enhancements to existing features:
- Performance optimizations
- Better error messages
- Improved UX/UI
- Enhanced reliability
Category: ⚠️ Breaking Changes
Changes requiring user action:
- API signature changes
- Removed features
- Changed default behavior
- Migration required
4. Filter for User-Facing Changes
Include:
- Changes users will notice
- Changes users need to know about
- Changes that affect how they use the product
- Security fixes (user-facing impact)
Exclude or minimize:
- Internal refactoring
- Test additions
- Build configuration changes
- Code style updates
- Developer tooling changes
Transform technical to user-friendly:
❌ "Refactored AuthService to use dependency injection"
✅ "Improved authentication reliability"
❌ "Updated webpack config for tree shaking"
✅ "Reduced bundle size by 20%"
❌ "Fixed race condition in concurrent processing"
✅ "Improved stability when processing multiple items simultaneously"
5. Generate Release Notes
Create formatted markdown output:
Template Structure
# Release Notes - Version X.Y.Z
**Release Date:** YYYY-MM-DD
## Summary
[1-3 sentence overview of the release]
---
## ✨ New Features
- **[Feature Title]**: [User-friendly description]
- **[Feature Title]**: [Description with benefit]
## 🚀 Improvements
- **[Improvement Title]**: [How this makes things better]
- **[Improvement Title]**: [Description]
## 🐛 Bug Fixes
- Fixed [issue description]
- Resolved [problem users were experiencing]
## ⚠️ Breaking Changes
- **[Breaking Change Title]**: [What changed and what users need to do]
- **Migration:** [Step-by-step guidance]
- **Before:** `code example`
- **After:** `code example`
---
## 📊 Statistics
- X features added
- Y bugs fixed
- Z improvements made
## 🙏 Contributors
Thank you to all contributors who made this release possible:
- @username1
- @username2
6. Write User-Friendly Descriptions
Make each change clear and valuable:
Use active, benefit-focused language:
❌ "Added pagination to API"
✅ "You can now request data in pages, making it easier to work with large datasets"
❌ "Implemented OAuth2 authentication"
✅ "Sign in with your Google, GitHub, or Microsoft account"
❌ "Optimized database queries"
✅ "Reports now load 3x faster"
Be specific about impact:
❌ "Performance improvements"
✅ "Search results now appear in under 100ms, down from 2 seconds"
❌ "Better error handling"
✅ "Error messages now include specific suggestions for fixing the issue"
Include code examples for API changes:
### Breaking Change: Authentication Method Updated
**Before:**
```python
client = APIClient(session_token="abc123")
After:
client = APIClient(api_key="sk-abc123")
Migration: Update your initialization code to use the new api_key parameter.
### 7. Review and Polish
Before finalizing:
**Check completeness:**
- ✅ All significant changes included?
- ✅ Breaking changes clearly marked?
- ✅ User action items specified?
- ✅ Version number correct?
**Check clarity:**
- ✅ Descriptions are user-friendly, not technical?
- ✅ Benefits are clear?
- ✅ No internal jargon?
- ✅ Examples provided where helpful?
**Check organization:**
- ✅ Changes grouped logically?
- ✅ Most important changes listed first?
- ✅ Breaking changes prominently displayed?
## Example Output
```markdown
# Release Notes - Version 2.3.0
**Release Date:** February 15, 2026
## Summary
Version 2.3.0 brings enhanced search capabilities, performance improvements, and several bug fixes.
---
## ✨ New Features
- **Advanced Search Filters**: Filter search results by date, category, and status for more precise results
- **Keyboard Shortcuts**: Navigate the app faster with new keyboard shortcuts (press `?` to see all)
- **Export to Excel**: Export your data to Excel format in addition to CSV
## 🚀 Improvements
- **Faster Search**: Search results now appear instantly (improved from 2s to <100ms)
- **Better Mobile Experience**: Optimized interface for mobile devices
- **Smarter Autocomplete**: Autocomplete suggestions now learn from your previous searches
## 🐛 Bug Fixes
- Fixed issue where saving large files would occasionally fail
- Resolved problem with date picker not working in Safari
- Corrected timezone display for users in Asia-Pacific regions
---
## 📊 Statistics
- 3 new features
- 4 bugs fixed
- 3 improvements
- 47 commits
- 8 contributors
## 🙏 Contributors
Thank you to: @alice, @bob, @charlie, @diana, @eve, @frank, @grace, @henry
Tips for Effective Release Notes
Focus on user value:
- What can users now do?
- What problems were solved?
- What's better/faster/easier?
Be honest about breaking changes:
- Mark them prominently
- Provide clear migration paths
- Explain why the cha