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: or feature: → New Feature
• fix: or bugfix: → Bug Fix
• perf: or performance: → Performance Improvement
• docs: or doc: → Documentation
• refactor: → Code Quality/Refactoring
• test: → Testing
• chore: → Internal/Maintenance
• BREAKING: 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 change was made

Use consistent language:

• Present tense: "You can now..." not "You will be able to..."
• Active voice: "Added feature" not "Feature was added"
• User-centric: "You can" not "The system allows"

Group related changes:

• Don't list every commit separately
• Combine related fixes/features
• Summarize multiple small improvements

Credit contributors:

• Acknowledge community contributions
• Thank external contributors
• Build goodwill and engagement