Changelog Generator

This skill transforms technical git commits into polished, user-friendly changelogs that your customers and users will actually understand and appreciate.

When to Use This Skill

• Preparing release notes for a new version
• Creating weekly or monthly product update summaries
• Documenting changes for customers
• Writing changelog entries for app store submissions
• Generating update notifications
• Creating internal release documentation
• Maintaining a public changelog/product updates page

What This Skill Does

1. Scans Git History: Analyzes commits from a specific time period or between versions
2. Categorizes Changes: Groups commits into logical categories (features, improvements, bug fixes, breaking changes, security)
3. Translates Technical → User-Friendly: Converts developer commits into customer language
4. Formats Professionally: Creates clean, structured changelog entries
5. Filters Noise: Excludes internal commits (refactoring, tests, etc.)
6. Follows Best Practices: Applies changelog guidelines and your brand voice

How to Use

Basic Usage

From your project repository:

Create a changelog from commits since last release

Generate changelog for all commits from the past week

Create release notes for version 2.5.0

With Specific Date Range

Create a changelog for all commits between March 1 and March 15

With Custom Guidelines

Create a changelog for commits since v2.4.0, using my changelog 
guidelines from CHANGELOG_STYLE.md

Instructions

When creating a changelog:

1. Analyze Git History

   • Use git log to retrieve commit messages for the specified time period
   • Default to commits since the last tag if no range specified
   • Look for commit conventions (Conventional Commits, semantic versioning tags)

2. Categorize Commits

   • ✨ New Features: New capabilities or functionality
   • 🔧 Improvements: Enhancements to existing features
   • 🐛 Bug Fixes: Corrections to defects
   • ⚠️ Breaking Changes: Changes that require user action
   • 🔒 Security: Security-related fixes or improvements
   • 📚 Documentation: Documentation updates (usually exclude from user-facing changelog)
   • 🧹 Internal: Refactoring, tests, build changes (exclude from user-facing changelog)

3. Transform Technical → User Language

   • Focus on what changed for the user, not how it was implemented
   • Use active voice and present tense
   • Explain the benefit, not the implementation
   • Replace technical jargon with plain language

   Examples:

   • ❌ “Refactored authentication service to use JWT tokens”

   • ✅ “Faster, more secure login experience”

   • ❌ “Added Redis caching layer to API endpoints”

   • ✅ “Pages load 50% faster”

   • ❌ “Implemented debounce on search input component”

   • ✅ “Search now responds instantly as you type”

4. Format the Changelog

   • Use clear section headers with emojis for visual scanning
   • Start with most impactful changes (features, breaking changes)
   • Use bold for the feature name, then explain in plain language
   • Keep entries concise (1-2 sentences)
   • Group related changes together

5. Apply Filters

   • Exclude commits marked as chore:, test:, docs:, refactor: (unless user-facing)
   • Skip merge commits and version bump commits
   • Combine multiple commits about the same feature into one entry
   • Remove developer-only changes

6. Add Context

   • Include the date or version number in the title
   • Add a brief introduction if it’s a major release
   • Link to detailed documentation for breaking changes
   • Include migration guides when relevant

Example

User: “Create a changelog for commits from the past 7 days”

Output:

# Updates - Week of March 10, 2024

## ✨ New Features

- **Team Workspaces**: Create separate workspaces for different 
  projects. Invite team members and keep everything organized.

- **Keyboard Shortcuts**: Press ? to see all available shortcuts. 
  Navigate faster without touching your mouse.

## 🔧 Improvements

- **Faster Sync**: Files now sync 2x faster across devices
- **Better Search**: Search now includes file contents, not just titles

## 🐛 Fixes

- Fixed issue where large images wouldn't upload
- Resolved timezone confusion in scheduled posts
- Corrected notification badge count

Inspired by: Manik Aggarwal’s use case from Lenny’s Newsletter

Changelog Best Practices

Writing Style

• User-focused: Explain what changed for the user, not the code
• Benefit-oriented: Lead with why this matters
• Concise: Keep entries to 1-2 sentences
• Scannable: Use formatting to help users find what they care about

Structure

• Consistent categorization: Use the same categories every time
• Most important first: Features and breaking changes before bug fixes
• Chronological within categories: Newest changes first
• Visual hierarchy: Use headers, bold text, and emojis effectively

Content Guidelines

• Be specific: “Fixed login issues” → “Fixed issue where login failed with Google accounts”
• Quantify when possible: “Faster loading” → “Pages load 50% faster”
• Include context: Explain why changes were made for major updates
• Link to details: Reference documentation or migration guides for complex changes

Tips

• Run from your git repository root
• Specify date ranges for focused changelogs
• Use your CHANGELOG_STYLE.md for consistent formatting
• Review and adjust the generated changelog before publishing
• Save output directly to CHANGELOG.md

Related Use Cases

• Creating GitHub release notes
• Writing app store update descriptions
• Generating email updates for users
• Creating social media announcement posts

Example Transformations

Technical Commit → User-Friendly Entry

Category Examples

✨ New Features

• New capabilities that didn’t exist before
• Major additions to functionality
• New integrations or platform support

🔧 Improvements

• Performance enhancements
• UI/UX refinements
• Expanded existing functionality
• Better error messages

🐛 Bug Fixes

• Corrections to existing features
• Resolution of reported issues
• Fixes to edge cases

⚠️ Breaking Changes

• Changes requiring user action
• Removed features or APIs
• Changes to default behavior
• Migration steps required

🔒 Security

• Security patches
• Permission improvements
• Authentication enhancements
• Data protection updates