change-log-generator

name

change-log-generator

description

Automatically generates change logs from git commits, patches, and pull requests. Use when preparing software releases, creating version summaries, or maintaining CHANGELOG.md files. Analyzes commit messages (including conventional commits), diff/patch files, and PR data to produce categorized Markdown change logs organized by type (Features, Bug Fixes, Breaking Changes, etc.). Ideal for release notes, version updates, and automated changelog maintenance.

Change Log Generator

Automatically generate comprehensive change logs from git history and code changes.

Core Capabilities

This skill helps create change logs by:

1. Analyzing git commits - Parse commit messages for changes
2. Processing conventional commits - Extract structured information from standardized commits
3. Examining diffs/patches - Understand code changes from git diff output
4. Categorizing changes - Automatically group by type (features, fixes, docs, etc.)
5. Formatting output - Generate Markdown change logs following best practices

Change Log Generation Workflow

Step 1: Gather Change Information

Collect commits and changes for the release period.

Determine Release Range:

# Changes since last tag
git log $(git describe --tags --abbrev=0)..HEAD --oneline

# Changes between two tags
git log v1.2.0..v1.3.0 --oneline

# Changes in last N commits
git log -n 50 --oneline

# Changes since specific date
git log --since="2024-01-01" --oneline

# Changes in current branch vs main
git log main..HEAD --oneline

Get Detailed Commit Information:

# Full commit messages
git log v1.2.0..HEAD --format="%H|%an|%ad|%s|%b" --date=short

# With file changes
git log v1.2.0..HEAD --name-status

# With diff stats
git log v1.2.0..HEAD --stat

Get Pull Request Information:

# Using GitHub CLI
gh pr list --state merged --base main --limit 50

# Get PR details
gh pr view 123 --json title,body,labels,mergedAt

Step 2: Parse Commit Messages

Extract meaningful information from commits.

Conventional Commit Format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Common Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting, missing semicolons, etc.)
• refactor: Code refactoring
• perf: Performance improvements
• test: Adding or updating tests
• build: Build system or external dependency changes
• ci: CI configuration changes
• chore: Other changes that don't modify src or test files

Examples:

feat(auth): add OAuth2 authentication

Implements OAuth2 authentication flow using Google provider.
Users can now sign in with their Google accounts.

Closes #45

fix(api): prevent race condition in user creation

Race condition occurred when multiple requests tried to create
the same user simultaneously. Added database constraint and
retry logic.

Fixes #123

docs: update installation instructions

Added troubleshooting section for Windows users.

BREAKING CHANGE: remove deprecated API endpoints

The /api/v1/users endpoint has been removed. Use /api/v2/users instead.

Parse Commit Messages:

import re

def parse_conventional_commit(message):
    """Parse conventional commit message."""
    # Pattern: type(scope): description
    pattern = r'^(\w+)(\(([^)]+)\))?:\s*(.+)$'
    match = re.match(pattern, message)

    if match:
        return {
            'type': match.group(1),
            'scope': match.group(3),
            'description': match.group(4),
            'breaking': 'BREAKING CHANGE' in message
        }
    else:
        return {
            'type': 'other',
            'scope': None,
            'description': message,
            'breaking': 'BREAKING CHANGE' in message
        }

# Example
commit = "feat(auth): add OAuth2 authentication"
parsed = parse_conventional_commit(commit)
# Returns: {'type': 'feat', 'scope': 'auth', 'description': 'add OAuth2 authentication', 'breaking': False}

See references/conventional_commits.md for detailed parsing rules.

Step 3: Categorize Changes

Group commits by change type.

Category Mapping:

CATEGORIES = {
    'feat': {
        'title': 'Features',
        'emoji': '✨',
        'description': 'New features and capabilities'
    },
    'fix': {
        'title': 'Bug Fixes',
        'emoji': '🐛',
        'description': 'Bug fixes and corrections'
    },
    'perf': {
        'title': 'Performance',
        'emoji': '⚡',
        'description': 'Performance improvements'
    },
    'refactor': {
        'title': 'Refactoring',
        'emoji': '♻️',
        'description': 'Code refactoring'
    },
    'docs': {
        'title': 'Documentation',
        'emoji': '📚',
        'description': 'Documentation updates'
    },
    'test': {
        'title': 'Testing',
        'emoji': '✅',
        'description': 'Test additions and updates'
    },
    'build': {
        'title': 'Build System',
        'emoji': '🏗️',
        'description': 'Build and dependency changes'
    },
    'ci': {
        'title': 'CI/CD',
        'emoji': '👷',
        'description': 'CI/CD changes'
    },
    'style': {
        'title': 'Code Style',
        'emoji': '💄',
        'description': 'Code style and formatting'
    },
    'chore': {
        'title': 'Chores',
        'emoji': '🔧',
        'description': 'Maintenance and chores'
    }
}

def categorize_commits(commits):
    """Categorize commits by type."""
    categorized = {}

    for commit in commits:
        parsed = parse_conventional_commit(commit['message'])
        commit_type = parsed['type']

        if commit_type not in categorized:
            categorized[commit_type] = []

        categorized[commit_type].append({
            'description': parsed['description'],
            'scope': parsed['scope'],
            'sha': commit['sha'][:7],
            'author': commit['author'],
            'breaking': parsed['breaking']
        })

    return categorized

Prioritize Categories:

Order of importance:

1. Breaking Changes (always first)
2. Features
3. Bug Fixes
4. Performance
5. Security
6. Deprecations
7. Other categories

Step 4: Format Change Log

Generate Markdown output following conventions.

Basic Template:

# Changelog

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

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

## [Unreleased]

### Added
- New feature A
- New feature B

### Changed
- Updated component X
- Improved performance of Y

### Deprecated
- Old API endpoint will be removed in v2.0

### Removed
- Deprecated feature Z

### Fixed
- Bug in authentication flow
- Memory leak in processor

### Security
- Fixed XSS vulnerability in input validation

Generate Changelog Entry:

def generate_changelog_entry(version, date, categorized_commits):
    """Generate changelog entry for a version."""
    lines = []

    # Header
    lines.append(f"## [{version}] - {date}\n")

    # Breaking Changes (if any)
    breaking_changes = []
    for category, commits in categorized_commits.items():
        for commit in commits:
            if commit.get('breaking'):
                breaking_changes.append(commit)

    if breaking_changes:
        lines.append("### ⚠️ BREAKING CHANGES\n")
        for change in breaking_changes:
            scope_str = f"**{change['scope']}**: " if change['scope'] else ""
            lines.append(f"- {scope_str}{change['description']} ({change['sha']})")
        lines.append("")

    # Regular categories
    category_order = ['feat', 'fix', 'perf', 'refactor', 'docs', 'test', 'build', 'ci', 'style', 'chore']

    for cat_type in category_order:
        if cat_type in categorized_commits:
            category_info = CATEGORIES.get(cat_type, {'title': cat_type.title()})
            lines.append(f"### {category_info['title']}\n")

            for commit in categorized_commits[cat_type]:
                if commit.get('breaking'):
                    continue  # Already listed in breaking changes

                scope_str = f"**{commit['scope']}**: " if commit['scope'] else ""
                lines.append(f"- {scope_str}{commit['description']} ([`{commit['sha']}`](link/to/commit/{commit['sha']}))")

            lines.append("")

    return "\n".join(lines)

Example Output:

## [1.3.0] - 2024-02-15

### ⚠️ BREAKING CHANGES

- **api**: remove deprecated /v1/users endpoint (a1b2c3d)

### Features

- **auth**: add OAuth2 authentication support ([`d4e5f6g`](link))
- **dashboard**: add real-time metrics visualization ([`h7i8j9k`](link))
- **api**: implement rate limiting for API endpoints ([`l0m1n2o`](link))

### Bug Fixes

- **auth**: prevent race condition in user creation ([`p3q4r5s`](link))
- **ui**: fix button alignment on mobile devices ([`t6u7v8w`](link))
- **api**: handle null values in request validation ([`x9y0z1a`](link))

### Performance

- **database**: optimize user query with indexes ([`b2c3d4e`](link))
- **api**: implement caching for frequently accessed data ([`f5g6h7i`](link))

### Documentation

- update installation instructions ([`j8k9l0m`](link))
- add troubleshooting guide ([`n1o2p3q`](link))

Step 5: Handle Special Cases

Address non-conventional commits and edge cases.

Non-Conventional Commits:

def categorize_non_conventional(message):
    """Categorize commits that don't follow conventional format."""
    message_lower = message.lower()

    # Keyword-based categorization
    if any(word in message_lower for word in ['add', 'implement', 'create']):
        return 'feat'
    elif any(word in message_lower for word in ['fix', 'resolve', 'correct', 'patch']):
        return 'fix'
    elif any(word in message_lower for word in ['update', 'improve', 'enhance']):
        return 'refactor'
    elif any(word in message_lower for word in ['doc', 'readme', 'comment']):
        return 'docs'
    elif any(word in message_lower for word in ['test', 'spec']):
        return 'test'
    else:
        return 'other'

Merge Commits:

# Exclude merge commits
git log --no-merges v1.2.0..HEAD

# Or include merge commits with special handling
git log --first-parent v1.2.0..HEAD

Pull Request Integration:

def extract_pr_info(commit_message):
    """Extract PR number from commit message."""
    # Pattern: (#123) or Merge pull request #123
    import re
    match = re.search(r'#(\d+)', commit_message)
    if match:
        return match.group(1)
    return None

def enhance_with_pr_data(commit, pr_number):
    """Enhance commit with PR metadata."""
    # Use gh CLI or GitHub API
    import subprocess
    import json

    result = subprocess.run(
        ['gh', 'pr', 'view', pr_number, '--json', 'title,labels,author'],
        capture_output=True,
        text=True
    )

    if result.returncode == 0:
        pr_data = json.loads(result.stdout)
        commit['pr_title'] = pr_data.get('title')
        commit['pr_labels'] = pr_data.get('labels', [])
        commit['pr_author'] = pr_data.get('author', {}).get('login')

    return commit

Step 6: Add Metadata and Links

Enrich changelog with helpful information.

Add Comparison Links:

## [1.3.0] - 2024-02-15

[Full Changelog](https://github.com/user/repo/compare/v1.2.0...v1.3.0)

### Features
...

Add Contributors:

# Get unique contributors
git log v1.2.0..v1.3.0 --format="%an <%ae>" | sort | uniq

## [1.3.0] - 2024-02-15

**Contributors:** @alice, @bob, @charlie

### Features
...

Add Issue References:

def extract_issue_refs(message):
    """Extract issue references from commit message."""
    import re
    # Patterns: #123, Closes #123, Fixes #123
    patterns = [
        r'#(\d+)',
        r'[Cc]loses?\s+#(\d+)',
        r'[Ff]ixes?\s+#(\d+)',
        r'[Rr]esolves?\s+#(\d+)'
    ]

    issues = set()
    for pattern in patterns:
        matches = re.findall(pattern, message)
        issues.update(matches)

    return list(issues)

# Format in changelog
# - Fix authentication bug (closes #123, #124)

Step 7: Validate and Publish

Review and finalize the changelog.

Validation Checklist:

• All significant changes included
• Breaking changes clearly marked
• Changes categorized correctly
• Links working (commits, PRs, issues)
• Version number follows semantic versioning
• Date is correct
• Contributors acknowledged
• No duplicate entries
• Formatting consistent

Update CHANGELOG.md:

# Prepend new entry to existing CHANGELOG.md
cat new_entry.md CHANGELOG.md > temp.md
mv temp.md CHANGELOG.md

# Commit the changelog
git add CHANGELOG.md
git commit -m "docs: update changelog for v1.3.0"

Create GitHub Release:

# Using gh CLI
gh release create v1.3.0 \
  --title "Version 1.3.0" \
  --notes-file new_entry.md

# Or manually via GitHub web interface

Quick Templates

Minimal Template

## [1.3.0] - 2024-02-15

### Added
- OAuth2 authentication
- Real-time metrics

### Fixed
- Race condition in user creation
- Mobile UI alignment

### Changed
- Optimized database queries
- Updated dependencies

Standard Template

## [1.3.0] - 2024-02-15

[Full Changelog](https://github.com/user/repo/compare/v1.2.0...v1.3.0)

### ⚠️ BREAKING CHANGES

- **api**: Removed deprecated /v1/users endpoint. Migrate to /v2/users ([#145](link))

### Features

- **auth**: Add OAuth2 authentication support ([#142](link)) @alice
- **dashboard**: Real-time metrics visualization ([#143](link)) @bob

### Bug Fixes

- **auth**: Prevent race condition in user creation ([#144](link)) @alice
- **ui**: Fix button alignment on mobile ([#146](link)) @charlie

### Performance

- **database**: Optimize user queries with indexes ([#147](link))

**Contributors:** @alice, @bob, @charlie

Comprehensive Template

# Changelog

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

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

## [Unreleased]

### In Progress
- Feature X under development
- Performance improvements being tested

## [1.3.0] - 2024-02-15

[Full Changelog](https://github.com/user/repo/compare/v1.2.0...v1.3.0) | [Release Notes](link)

> **Highlights:** This release adds OAuth2 authentication and significantly improves performance.

### ⚠️ BREAKING CHANGES

- **api**: Removed deprecated /v1/users endpoint
  - **Migration Guide:** Replace `/v1/users` with `/v2/users` in your API calls
  - **Impact:** Applications using the old endpoint will receive 404 errors
  - See [Migration Guide](link) for details

### ✨ Features

- **auth**: Add OAuth2 authentication support ([`a1b2c3d`](link)) ([#142](link))
  - Supports Google and GitHub providers
  - Automatic account creation on first login
  - Thanks to @alice for implementation
- **dashboard**: Real-time metrics visualization ([`d4e5f6g`](link)) ([#143](link))
  - Live update every 5 seconds
  - Customizable dashboard widgets
- **api**: Implement rate limiting ([`h7i8j9k`](link)) ([#148](link))
  - 100 requests per minute per IP
  - Configurable via environment variables

### 🐛 Bug Fixes

- **auth**: Prevent race condition in user creation ([`l0m1n2o`](link)) ([#144](link))
  - Fixed duplicate user creation
  - Added database constraint
- **ui**: Fix button alignment on mobile devices ([`p3q4r5s`](link)) ([#146](link))
- **api**: Handle null values in validation ([`t6u7v8w`](link)) ([#149](link))

### ⚡ Performance

- **database**: Optimize user queries with indexes ([`x9y0z1a`](link)) ([#147](link))
  - 70% faster user lookups
  - Reduced database load
- **api**: Implement response caching ([`b2c3d4e`](link)) ([#150](link))
  - 50% reduction in API response time

### 📚 Documentation

- Update installation instructions ([`f5g6h7i`](link))
- Add troubleshooting guide ([`j8k9l0m`](link))
- Improve API documentation ([`n1o2p3q`](link))

### 🏗️ Build System

- Update dependencies to latest versions ([`r4s5t6u`](link))
- Add Docker support for development ([`v7w8x9y`](link))

### 🧪 Testing

- Add integration tests for auth flow ([`z0a1b2c`](link))
- Improve test coverage to 85% ([`d3e4f5g`](link))

### 👷 CI/CD

- Add automated deployment to staging ([`h6i7j8k`](link))
- Implement security scanning in CI ([`l9m0n1o`](link))

**New Contributors:**
- @alice made their first contribution in #142
- @bob improved the dashboard in #143

**Full Contributor List:** @alice, @bob, @charlie, @david

**Download:** [v1.3.0 Release](link)

---

## [1.2.0] - 2024-01-15

[Previous release notes...]

Automation Scripts

Generate Changelog Script

#!/bin/bash
# generate_changelog.sh - Generate changelog between two tags

FROM_TAG=${1:-$(git describe --tags --abbrev=0 HEAD^)}
TO_TAG=${2:-HEAD}
VERSION=${3:-"Unreleased"}
DATE=$(date +%Y-%m-%d)

echo "# Changelog Entry for $VERSION"
echo ""
echo "## [$VERSION] - $DATE"
echo ""

# Get commits
git log $FROM_TAG..$TO_TAG --format="%s" --no-merges | while read commit; do
    # Parse conventional commit
    if [[ $commit =~ ^([a-z]+)(\(([^)]+)\))?:\ (.+)$ ]]; then
        type="${BASH_REMATCH[1]}"
        scope="${BASH_REMATCH[3]}"
        desc="${BASH_REMATCH[4]}"

        case $type in
            feat)
                echo "### Features" >> /tmp/feat.txt
                echo "- $desc" >> /tmp/feat.txt
                ;;
            fix)
                echo "### Bug Fixes" >> /tmp/fix.txt
                echo "- $desc" >> /tmp/fix.txt
                ;;
            docs)
                echo "### Documentation" >> /tmp/docs.txt
                echo "- $desc" >> /tmp/docs.txt
                ;;
        esac
    fi
done

# Output in order
for file in /tmp/{feat,fix,docs}.txt; do
    if [ -f "$file" ]; then
        cat "$file" | sort | uniq
        echo ""
        rm "$file"
    fi
done

See references/automation_examples.md for more complete scripts.

Best Practices

1. Use conventional commits - Makes categorization automatic
2. Include issue/PR references - Provides context and traceability
3. Highlight breaking changes - Critical for users upgrading
4. Keep entries concise - One line per change, link to details
5. Use present tense - "Add feature" not "Added feature"
6. Group by category - Easier to scan and understand
7. Add migration guides - For breaking changes
8. Link to commits/PRs - Enables deeper investigation
9. Acknowledge contributors - Recognize team efforts
10. Update regularly - Don't wait until release day

Resources

• references/conventional_commits.md - Detailed guide to conventional commit format and parsing rules
• references/keep_a_changelog.md - Keep a Changelog format specification and examples
• references/automation_examples.md - Complete scripts for automating changelog generation

Quick Reference

Task	Command
Commits since last tag	git log $(git describe --tags --abbrev=0)..HEAD
Commits between tags	git log v1.2.0..v1.3.0
No merge commits	git log --no-merges
With file changes	git log --name-status
Contributors	git log --format="%an" | sort | uniq
PR info	gh pr view 123 --json title,body
Create release	gh release create v1.3.0 --notes-file changelog.md

Common Patterns

Pattern 1: Quick release notes

git log v1.2.0..v1.3.0 --oneline --no-merges | \
  sed 's/^[a-f0-9]* /- /' > release_notes.md

Pattern 2: Group by author

git log v1.2.0..v1.3.0 --format="%an: %s" --no-merges | \
  sort | uniq

Pattern 3: Extract breaking changes

git log v1.2.0..v1.3.0 --format="%B" --no-merges | \
  grep -A 5 "BREAKING CHANGE"