Generating Changelog

Git Changelog Generation

Automatically analyze git commit history and generate comprehensive changelogs following industry-standard formats.

Auto-Invoke Triggers

This skill automatically activates when:

1. Editing changelog files: CHANGELOG.md, CHANGELOG.txt, HISTORY.md 2. Mentioning keywords: "changelog", "release notes", "version", "semantic versioning" 3. Git tagging operations: Creating or discussing version tags 4. Release preparation: Discussing release preparation or deployment

What This Skill Delivers

When invoked, this skill provides:

1. Git History Analysis Report

• Commit range analysis (since last tag or specified range)
• Commit categorization by type (feat, fix, docs, etc.)
• Semantic version bump recommendation (MAJOR, MINOR, PATCH)
• Breaking changes detection
• Author and PR number extraction

2. Formatted Changelog

Choose from multiple formats:

• Keep a Changelog (default) - Industry standard, human-friendly
• Conventional - Follows Conventional Commits specification
• GitHub - GitHub-style release notes with PR links

3. Update Strategy

• Append to existing CHANGELOG.md (preserves history)
• Overwrite with fresh changelog
• Create new version section
• Merge with existing sections

Common Use Cases

Project Types

• Microservices: Track changes across multiple services
• Frontend Applications: UI updates and features
• API Development: REST API versioning and breaking changes
• Infrastructure: Deployment, CI/CD, DevOps updates
• Documentation: Technical docs, API docs, guides

Conventional Commit Examples

The skill recognizes standard commit conventions:

feat: add new authentication endpoint
fix: resolve token expiration issue
docs: update API documentation
refactor: optimize database queries
perf: improve calculation performance
test: add integration tests
build: upgrade framework version
ci: configure automated testing
chore: update dependencies

Monorepo Support

The skill handles monorepo structures:

• Service-specific changelogs (e.g., services/api/CHANGELOG.md)
• Frontend changelog (frontend/CHANGELOG.md)
• Root changelog (project-wide changes)

Technical Features

Conventional Commits Support

Automatically categorizes commits by type:

• feat: → Features section
• fix: → Bug Fixes section
• docs: → Documentation section
• style: → Code Style section
• refactor: → Refactoring section
• perf: → Performance section
• test: → Testing section
• build: → Build System section
• ci: → CI/CD section
• chore: → Other Changes section

Semantic Versioning Detection

Automatically suggests version bumps:

• MAJOR (x.0.0): Contains BREAKING CHANGE: or exclamation mark suffix
• MINOR (0.x.0): Contains feat: commits
• PATCH (0.0.x): Contains only fix: commits

Breaking Changes Detection

Identifies breaking changes from:

• BREAKING CHANGE: footer in commit message
• Exclamation mark after commit type (example: feat!: or fix!:)
• Manual annotation in commit body

GitHub Integration

Extracts from commit messages:

• Pull request numbers (#123)
• Issue references (#456)
• Author information
• Commit SHAs

Output Example

# 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.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [1.2.0] - 2025-10-22

### Added
- Keyword competition scoring algorithm for market analysis (#123)
- Multi-currency support for revenue calculations (#124)
- OpenSearch faceted search with Valkey caching (#125)

### Fixed
- JWT token expiration issue in user-service (#126)
- Race condition in favorite-service list operations (#127)
- Memory leak in trend-service ARIMA calculations (#128)

### Changed
- Upgraded Spring Boot to 3.4.3 across all services (#129)
- Optimized search-service query performance (40% improvement) (#130)
- Refactored supply-analytics-service ETL pipeline (#131)

### Security
- Updated Jackson to fix CVE-2025-12345 (#132)

### Performance
- Reduced trend-service calculation time from 2.5s to 0.8s (#133)

## [1.1.0] - 2025-09-15

...

Progressive Disclosure

This is Level 1 documentation (skill overview).

For more details, see:

• Level 2: WORKFLOW.md - Step-by-step methodology
• Level 3: EXAMPLES.md - Real-world usage examples
• Level 4: TROUBLESHOOTING.md - Common issues and solutions

Usage

Via Command

/changelog
/changelog --since v1.1.0 --version 1.2.0
/changelog --format github --append

Auto-Invoke

The skill activates automatically when:

# Editing changelog
vim CHANGELOG.md

# Discussing releases
"I need to prepare release notes for version 1.2.0"

# Git tagging
"Let's create a changelog for the v1.2.0 tag"

Integration with Development Workflow

Pre-Release Workflow

1. Developer: git tag v1.2.0-rc1 2. Skill auto-invokes: Analyzes commits since v1.1.0 3. Skill generates: Draft changelog with categorized changes 4. Developer reviews: Edits descriptions, adds context 5. Developer: /changelog --append --version 1.2.0 6. Skill updates: CHANGELOG.md with final content 7. Developer commits: Changelog as part of release

Service-Specific Releases

# Generate changelog for specific service
cd services/api
/changelog --output CHANGELOG.md --since v1.0.0

Monorepo Root Changelog

# Generate project-wide changelog
/changelog --output CHANGELOG.md --format keepachangelog

Quality Standards

• Conventional Commits: 100% recognition of conventional commit format
• Semantic Versioning: Automatic MAJOR/MINOR/PATCH detection
• Breaking Changes: Clear highlighting of breaking changes
• PR Linking: Automatic GitHub PR number extraction
• Date Formatting: ISO 8601 dates (YYYY-MM-DD)
• Markdown Formatting: Valid markdown with proper headers
• No Claude Code Footer: Never include Claude Code attribution in changelog entries unless explicitly requested by user

See Also

• doc-coauthoring skill - Collaborative documentation workflow
• /code-explain - Explain complex code sections
• diagramming skill or /diagram command - Generate diagrams (e.g., release flow diagrams)

Version

1.0.0

Changelog Generator Examples

Real-world scenarios for generating changelogs in the your project monorepo.

Example 1: Service Release (user-service v1.2.0)

Context

User-service needs a release with JWT improvements and bug fixes.

Command

cd backend/user-service
/changelog --since v1.1.0 --version 1.2.0 --append

Git History (user-service)

feat: add JWT token refresh endpoint (#145)
fix: resolve token expiration race condition (#146)
docs: update API documentation for auth endpoints
test: add integration tests for JWT refresh flow
chore: upgrade Spring Security to 6.2.1

Generated Changelog

# Changelog

All notable changes to the User Service will be documented in this file.

## [1.2.0] - 2025-10-22

### Added
- JWT token refresh endpoint for improved session management (#145)

### Fixed
- Token expiration race condition in authentication flow (#146)

### Changed
- Upgraded Spring Security to 6.2.1 for security improvements

## [1.1.0] - 2025-09-15

...

Skill Output

✅ Changelog generated successfully
📊 Analysis:
   - 5 commits analyzed
   - Version bump: MINOR (1.1.0 → 1.2.0)
   - Categories: 1 feat, 1 fix, 1 docs, 1 test, 1 chore
   - Breaking changes: 0

📝 Updated: backend/user-service/CHANGELOG.md
🏷️  Suggested tag: git tag -a v1.2.0 -m "Release v1.2.0"

Example 2: Frontend Release (web-ui v2.1.0)

Context

Major UI update with new component library and theme changes.

Command

cd frontend/web-ui
/changelog --format keepachangelog --version 2.1.0

Git History (web-ui)

✨ feat: integrate data table component for keyword research (#201)
💰 feat: add multi-currency support in revenue dashboard (#202)
⚛️ feat!: migrate from Redux to TanStack Query + Zustand (#203)
🔧 fix: resolve hydration errors in Next.js 14 (#204)
⚡ perf: optimize bundle size (reduced by 30%) (#205)
🎨 style: update theme to coral color preset (#206)
📚 docs: add component library integration guide

Generated Changelog

# Changelog

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

## [v2.1.0] — *2025-10-22* — ✨ **Frontend Enhancement Release**

**Frontend**
- 🧩 Integrated data table component for keyword research with sorting, filtering, and pagination (#201)
- 💰 Added multi-currency support in revenue dashboard with automatic USD conversion (#202)
- 🎨 Updated theme to coral color preset for improved visual consistency (#206)
- **BREAKING**: ⚛️ Migrated state management from Redux to TanStack Query + Zustand (#203)
  - Redux store removed - see migration guide
  - React Query now handles server state
  - Zustand manages client UI state

**Bug Fixes**
- 🔧 Resolved Next.js 14 hydration errors in server components (#204)

**Performance**
- ⚡ Reduced bundle size by 30% through code splitting and lazy loading (#205)

## [v2.0.0] — *2025-08-01* — 🚀 **Major Architecture Release**

...

Skill Output

⚠️  BREAKING CHANGES DETECTED
📊 Analysis:
   - 7 commits analyzed
   - Version format: v2.1.0 (Nos Ilha style with emojis)
   - Version bump: MAJOR (v2.0.0 → v2.1.0) - Contains breaking change
   - Component sections: Frontend, Bug Fixes, Performance
   - Emoji prefixes: ✨ feat, 🔧 fix, ⚡ perf, 🎨 style, 📚 docs
   - Breaking changes: 1 (state management migration)

🚨 Breaking Change Details:
   - Commit: ⚛️ feat!: migrate from Redux to TanStack Query + Zustand (#203)
   - Impact: State management architecture change
   - Action Required: Update consuming components

📝 Updated: frontend/web-ui/CHANGELOG.md
🏷️  Suggested tag: git tag -a v2.1.0 -m "Frontend Enhancement Release v2.1.0"

Example 3: Monorepo Root Release (v1.5.0)

Context

Project-wide release affecting multiple services and common-libs.

Command

# From monorepo root
/changelog --since v1.4.0 --version 1.5.0 --format github

Git History (monorepo)

feat(common-libs): add ApiResponse standardization (#301)
feat(search-service): integrate OpenSearch with Valkey cache (#302)
feat(supply-analytics): add competition scoring algorithm (#303)
fix(trend-service): resolve ARIMA calculation accuracy (#304)
fix(favorite-service): fix race condition in list operations (#305)
docs: update architecture documentation
build: upgrade Spring Boot to 3.4.3 across all services (#306)
ci: configure GitHub Actions for automated testing (#307)

Generated Changelog (GitHub Format)

# Changelog

## What's Changed in v1.5.0

**New Features:**
- Added ApiResponse standardization in common-libs by @johndoe in #301
- Integrated OpenSearch with Valkey cache in search-service by @janesmith in #302
- Added keyword competition scoring algorithm in supply-analytics by @bobsmith in #303

**Bug Fixes:**
- Resolved ARIMA calculation accuracy in trend-service by @alicejones in #304
- Fixed race condition in favorite-service list operations by @johndoe in #305

**Infrastructure:**
- Upgraded Spring Boot to 3.4.3 across all services by @devops in #306
- Configured GitHub Actions for automated testing by @devops in #307

**Documentation:**
- Updated architecture documentation

**Full Changelog**: v1.4.0...v1.5.0

**Contributors:**
@johndoe, @janesmith, @bobsmith, @alicejones, @devops

Skill Output

✅ Monorepo changelog generated
📊 Analysis:
   - 8 commits analyzed (across 5 services + common-libs)
   - Version bump: MINOR (1.4.0 → 1.5.0)
   - Services affected: common-libs, search-service, supply-analytics-service, trend-service, favorite-service
   - Categories: 3 feat, 2 fix, 1 docs, 1 build, 1 ci
   - Breaking changes: 0

📝 Updated: CHANGELOG.md (root)
🏷️  Suggested tag: git tag -a v1.5.0 -m "Release v1.5.0"

Example 4: Patch Release (search-service v1.1.1)

Context

Hotfix release for search-service with only bug fixes.

Command

cd backend/search-service
/changelog --since v1.1.0 --version 1.1.1 --append

Git History (search-service)

fix: resolve OpenSearch connection timeout (#401)
fix: correct facet aggregation for keyword filters (#402)
test: add integration tests for timeout scenarios

Generated Changelog

# Changelog

## [1.1.1] - 2025-10-22

### Fixed
- OpenSearch connection timeout during high load scenarios (#401)
- Facet aggregation incorrect results for keyword filters (#402)

## [1.1.0] - 2025-10-15

...

Skill Output

✅ Patch release generated
📊 Analysis:
   - 3 commits analyzed
   - Version bump: PATCH (1.1.0 → 1.1.1)
   - Categories: 2 fix, 1 test
   - Breaking changes: 0
   - ⚡ Hotfix recommended for production

📝 Updated: backend/search-service/CHANGELOG.md
🏷️  Suggested tag: git tag -a v1.1.1 -m "Hotfix v1.1.1"

Example 5: Pre-Release (common-libs v1.6.0-rc1)

Context

Release candidate for common-libs before production deployment.

Command

cd backend/common-libs
/changelog --since v1.5.5 --version 1.6.0-rc1 --format conventional

Git History (common-libs)

feat: add distributed tracing utilities (#501)
feat: add rate limiting interceptor (#502)
refactor: optimize ApiResponse serialization (#503)
test: add performance benchmarks for ApiResponse
docs: update JavaDoc for new tracing utilities

Generated Changelog (Conventional Format)

# Changelog

## 1.6.0-rc1 (2025-10-22)

#### Features
* feat: add distributed tracing utilities for microservices (abc123) #501
* feat: add rate limiting interceptor for API endpoints (def456) #502

#### Code Refactoring
* refactor: optimize ApiResponse serialization for better performance (ghi789) #503

#### Documentation
* docs: update JavaDoc for new tracing utilities (jkl012)

#### Tests
* test: add performance benchmarks for ApiResponse (mno345)

Skill Output

✅ Pre-release changelog generated
📊 Analysis:
   - 5 commits analyzed
   - Version bump: MINOR → PRE-RELEASE (1.5.5 → 1.6.0-rc1)
   - Categories: 2 feat, 1 refactor, 1 docs, 1 test
   - Breaking changes: 0
   - 🧪 Pre-release: Requires testing before stable release

⚠️  Next Steps:
   1. Deploy to staging environment
   2. Run integration tests
   3. If successful: /changelog --version 1.6.0 (stable)

📝 Updated: backend/common-libs/CHANGELOG.md
🏷️  Suggested tag: git tag -a v1.6.0-rc1 -m "Release candidate v1.6.0-rc1"

Example 6: Date Range (Monthly Summary)

Context

Generate monthly changelog for October 2025 progress report.

Command

/changelog --since "2025-10-01" --until "2025-10-31" --output OCTOBER_2025.md

Generated Output

# October 2025 Progress Report

## Summary
- Total commits: 47
- Contributors: 5 (@johndoe, @janesmith, @bobsmith, @alicejones, @devops)
- Services updated: 8
- Features: 12
- Bug fixes: 8
- Performance improvements: 3

## Features Delivered

### Backend Services
- Keyword competition scoring algorithm (supply-analytics-service) #303
- JWT token refresh endpoint (user-service) #145
- OpenSearch integration with Valkey cache (search-service) #302

### Frontend
- Data table integration (web-ui) #201
- Multi-currency revenue dashboard (web-ui) #202
- Theme presets (web-ui) #206

### Infrastructure
- Distributed tracing utilities (common-libs) #501
- GitHub Actions CI/CD pipeline (root) #307

## Bug Fixes

### Critical
- JWT token expiration race condition (user-service) #146
- ARIMA calculation accuracy (trend-service) #304

### High Priority
- Next.js hydration errors (web-ui) #204
- OpenSearch connection timeout (search-service) #401

## Performance Improvements
- 30% bundle size reduction (web-ui) #205
- ApiResponse serialization optimization (common-libs) #503
- Search service query optimization (search-service) #302

## Infrastructure Updates
- Spring Boot upgraded to 3.4.3 across all services #306
- Spring Security upgraded to 6.2.1 (user-service)

## Documentation
- Architecture documentation updated
- Component library integration guide added
- API documentation updated for auth endpoints

## Testing
- Integration tests added for JWT refresh flow
- Performance benchmarks added for ApiResponse
- Timeout scenario tests for search-service

Skill Output

✅ Monthly summary generated
📊 Analysis:
   - Date range: 2025-10-01 to 2025-10-31
   - 47 commits analyzed
   - 5 contributors
   - 8 services affected

📝 Created: OCTOBER_2025.md

Next Steps

• Level 4: See TROUBLESHOOTING.md for common issues and solutions

Version

1.0.0

Changelog Generator Troubleshooting

Common issues and solutions when generating changelogs in your project.

Common Issues

Issue 1: "Not a git repository"

Symptom:

Error: fatal: not a git repository (or any of the parent directories): .git

Cause:

• Not in a git-initialized directory
• Working in a directory outside the your project monorepo

Solution:

# Verify you're in a git repository
git rev-parse --is-inside-work-tree

# Navigate to your project monorepo root
cd /Users/username/Projects/your-project

# Or navigate to specific service
cd backend/user-service

Prevention:

• Always run /changelog from within a git repository
• Check pwd before running the command

---

Issue 2: "No commits found in range"

Symptom:

Error: No commits found between v1.1.0 and HEAD
Warning: Cannot generate changelog with empty commit range

Cause:

• No new commits since last tag
• Incorrect tag name (typo or non-existent tag)
• Working on a branch without new commits

Solution:

# Check existing tags
git tag --list

# Verify commits exist in range
git log v1.1.0..HEAD --oneline

# If no commits, check current branch
git branch --show-current

# Check if on correct branch
git checkout main

Alternative:

# Generate changelog for specific commit range
/changelog --since abc123 --until def456

# Or use date range instead
/changelog --since "2025-10-01" --until "2025-10-22"

Prevention:

• Always verify commits exist before generating changelog
• Use git log to check commit range

---

Issue 3: "Invalid version format"

Symptom:

Error: Cannot parse version "v1.x.0"
Expected format: MAJOR.MINOR.PATCH (e.g., 1.2.0)

Cause:

• Non-semantic versioning format
• Typo in version number
• Missing PATCH version (e.g., "1.2" instead of "1.2.0")

Solution:

# Use proper semantic versioning
/changelog --version 1.2.0

# NOT: /changelog --version 1.2
# NOT: /changelog --version v1.x.0

Valid Formats:

• 1.2.0 ✅
• 1.2.0-rc1 ✅ (pre-release)
• 1.2.0-beta.1 ✅ (pre-release with metadata)
• v1.2.0 ❌ (remove 'v' prefix)
• 1.2 ❌ (missing PATCH)

Prevention:

• Always use MAJOR.MINOR.PATCH format
• Omit 'v' prefix (added automatically by skill)

---

Issue 4: "Duplicate version entry"

Symptom:

Warning: CHANGELOG.md already contains entry for v1.2.0
Conflicting versions detected

Cause:

• Version already exists in CHANGELOG.md
• Running command multiple times for same version
• Manual edits conflicting with generated content

Solution Option A: Overwrite

# Overwrite existing entry
/changelog --version 1.2.0 --overwrite

Solution Option B: Skip

# Skip generation if version exists
/changelog --version 1.2.0 --skip-if-exists

Solution Option C: Increment Version

# Use next version instead
/changelog --version 1.2.1

Prevention:

• Check CHANGELOG.md before generating
• Use --append mode (default) to avoid conflicts
• Delete old entry manually before regenerating

---

Issue 5: "Malformed commit messages"

Symptom:

Warning: 12 commits do not follow Conventional Commits format
These commits will be categorized as "Other Changes"

Cause:

• Commits don't follow type: subject format
• Missing colon after type
• Invalid commit type (not feat, fix, docs, etc.)

Solution:

# Review malformed commits
git log --oneline --grep="^[^:]*$"

# Manually categorize in changelog
# Edit CHANGELOG.md after generation

Example Malformed Commits:

❌ Added new feature
❌ Fixing bug in user service
❌ update docs

Correct Format:

✅ feat: add new feature
✅ fix: resolve bug in user service
✅ docs: update documentation

Prevention:

• Use Conventional Commits for all future commits
• Configure git commit hooks to validate format
• Educate team on commit message standards

---

Issue 6: "Breaking changes not detected"

Symptom:

Generated changelog shows MINOR bump but should be MAJOR
Breaking change commits not highlighted in changelog

Cause:

• Breaking change not properly annotated
• Missing exclamation mark after commit type
• Missing BREAKING CHANGE: footer

Solution: Properly annotate breaking changes using one of these methods:

Method 1: Exclamation Mark

git commit -m "feat!: migrate from Redux to TanStack Query

BREAKING CHANGE: Redux store removed, state management refactored"

Method 2: Footer

git commit -m "refactor: change API response format

BREAKING CHANGE: API response format changed from array to object"

Method 3: Rewrite Commit Message

# Amend last commit
git commit --amend

# Or interactive rebase for older commits
git rebase -i HEAD~5

Prevention:

• Always use feat!: or fix!: for breaking changes
• Include BREAKING CHANGE: footer with detailed description
• Review commits before tagging release

---

Issue 7: "Missing PR numbers"

Symptom:

Changelog entries missing GitHub PR links
Expected: "Add feature (#123)"
Actual: "Add feature"

Cause:

• Commits don't reference PR numbers
• PR numbers not in standard format (#123)
• Manual commits instead of GitHub merge commits

Solution:

# Manually add PR numbers in commit messages
git commit -m "feat: add feature (#123)"

# Or use GitHub's merge commit message (automatic)
# "Merge pull request #123 from branch-name"

# Rewrite commit messages to add PR numbers
git rebase -i HEAD~5

Alternative:

# Generate changelog and manually add PR links
/changelog --version 1.2.0

# Edit CHANGELOG.md to add missing PR numbers
vim CHANGELOG.md

Prevention:

• Always merge PRs using GitHub's "Merge pull request" button
• Include PR number in commit message: (#123)
• Configure branch protection to require PR workflow

---

Issue 8: "Monorepo commits grouped incorrectly"

Symptom:

All commits appear in root changelog
Service-specific changelogs are empty

Cause:

• Running command from wrong directory
• Not filtering commits by service path
• Monorepo structure not recognized

Solution:

# Generate service-specific changelog
cd backend/user-service
/changelog --version 1.2.0

# Filter commits by path (manual)
git log v1.1.0..HEAD --oneline -- backend/user-service/

# Or specify path filter
/changelog --path backend/user-service

Monorepo Best Practices:

• Root changelog: Project-wide changes affecting multiple services
• Service changelogs: Service-specific changes only
• Run command from service directory for service-specific changelogs

Prevention:

• Always cd to correct directory before generating
• Use --path filter for monorepo commits

---

Issue 9: "Changelog format incorrect"

Symptom:

Generated changelog doesn't match expected format
Sections out of order or missing

Cause:

• Incorrect format specified
• Custom format expectations not met
• Missing category mapping

Solution:

# Specify format explicitly
/changelog --format keepachangelog  # Industry standard
/changelog --format conventional    # Conventional Commits
/changelog --format github          # GitHub release notes

Format Comparison:

Prevention:

• Choose format before generating
• Review format examples in EXAMPLES.md
• Use consistent format across project

---

Issue 10: "Performance issues with large repositories"

Symptom:

Command hangs or takes >30 seconds
Memory errors with large commit history

Cause:

• Analyzing thousands of commits
• Large monorepo with multiple services
• Inefficient git operations

Solution:

# Limit commit range
/changelog --since v1.9.0 --until HEAD  # Last version only

# Use date range instead of full history
/changelog --since "2025-10-01"

# Generate incrementally (per service)
cd backend/user-service && /changelog
cd backend/search-service && /changelog

Optimization:

# Use shallow clone for faster operations
git log --since="2025-10-01" --pretty=format:"%s" | head -100

Prevention:

• Always specify commit range with --since
• Avoid generating changelogs for entire repository history
• Use service-specific changelogs in monorepo

---

Quick Diagnostics

Checklist Before Running Command

# 1. Verify git repository
git rev-parse --is-inside-work-tree

# 2. Check current directory
pwd

# 3. Verify commits exist
git log --oneline | head -10

# 4. Check existing tags
git tag --list | tail -5

# 5. Verify commit range
git log v1.1.0..HEAD --oneline

# 6. Check for existing changelog
test -f CHANGELOG.md && echo "Exists" || echo "Will create new"

Debug Mode

# Enable verbose output
/changelog --verbose --version 1.2.0

# Dry run (preview without writing)
/changelog --dry-run --version 1.2.0

# Show detected commits
git log v1.1.0..HEAD --pretty=format:"%h %s" | head -20

Getting Help

Skill Documentation

• SKILL.md - Overview and triggers
• WORKFLOW.md - Step-by-step methodology
• EXAMPLES.md - Real-world your project scenarios

your project Resources

• CLAUDE.md - Main project guidance
• ARCHITECTURE.md - System architecture
• Service-specific CLAUDE.md files

External Resources

• Conventional Commits
• Keep a Changelog
• Semantic Versioning

Version

1.0.0

Changelog Generator Workflow

Step-by-step methodology for generating professional changelogs from git history.

Overview

The changelog skill follows a 6-phase workflow: 1. Context Analysis - Understand repository and versioning scheme 2. Git History Analysis - Extract and parse commit history 3. Commit Categorization - Group commits by conventional commit types 4. Version Detection - Determine semantic version bump 5. Changelog Generation - Format output in requested style 6. Update & Validation - Write to file and validate markdown

Phase 1: Context Analysis

Repository Detection

# Check if in git repository
git rev-parse --is-inside-work-tree

# Detect if monorepo (multiple services)
ls backend/*/CLAUDE.md frontend/*/CLAUDE.md

# Identify current service (if in subdirectory)
pwd | grep -E "(backend|frontend)/([^/]+)"

Versioning Scheme Detection

# Check for existing tags
git tag --list

# Identify versioning pattern
git tag --list | head -5
# Examples:
#   v1.0.0, v1.1.0 → Semantic versioning with 'v' prefix
#   1.0.0, 1.1.0 → Semantic versioning without prefix
#   2025.10.22 → CalVer (calendar versioning)

Changelog Location

# Check for existing changelog
test -f CHANGELOG.md && echo "Exists" || echo "Create new"

# Monorepo: Check service-specific changelog
test -f backend/user-service/CHANGELOG.md

Output: Repository context (monorepo vs single, versioning scheme, changelog location)

Phase 2: Git History Analysis

Commit Range Determination

# Option A: Since last tag (default)
SINCE=$(git describe --tags --abbrev=0)
UNTIL="HEAD"

# Option B: User-specified range
SINCE="v1.1.0"
UNTIL="v1.2.0"

# Option C: Date range
SINCE="2025-01-01"
UNTIL="2025-10-22"

Commit Extraction

# Get commits with metadata
git log $SINCE..$UNTIL \
  --pretty=format:"%H|%an|%ae|%ad|%s|%b" \
  --date=short

# Example output:
# abc123|John Doe|john@example.com|2025-10-22|feat: add keyword scoring|PR #123
# def456|Jane Smith|jane@example.com|2025-10-21|fix: resolve JWT issue|Fixes #124

Commit Parsing

For each commit, extract:

• Hash: First 7 chars (abc123)
• Author: Name and email
• Date: ISO 8601 format
• Type: feat, fix, docs, etc. (from conventional commit prefix)
• Scope: Optional scope in parentheses (e.g., feat(api):)
• Subject: Commit message subject line
• Body: Full commit message body
• Footer: Metadata (PR numbers, issue refs, breaking changes)

Output: Structured commit data (JSON or array)

Phase 3: Commit Categorization

Conventional Commit Type Detection

# Regex pattern for conventional commits
pattern = r'^(?P<type>feat|fix|docs|style|refactor|perf|test|build|ci|chore)(?:\((?P<scope>[^)]+)\))?(?P<breaking>!)?:\s+(?P<subject>.+)$'

# Categorize commits
categories = {
    'feat': [],      # Features
    'fix': [],       # Bug Fixes
    'docs': [],      # Documentation
    'style': [],     # Code Style
    'refactor': [],  # Refactoring
    'perf': [],      # Performance
    'test': [],      # Testing
    'build': [],     # Build System
    'ci': [],        # CI/CD
    'chore': [],     # Other
}

Breaking Changes Detection

# Method 1: Exclamation mark after type
if commit.breaking:  # feat!: or fix!:
    breaking_changes.append(commit)

# Method 2: BREAKING CHANGE footer
if 'BREAKING CHANGE:' in commit.footer:
    breaking_changes.append(commit)

# Method 3: Manual annotation in body
if re.search(r'\[breaking\]', commit.body, re.IGNORECASE):
    breaking_changes.append(commit)

GitHub Metadata Extraction

# Extract PR numbers
pr_numbers = re.findall(r'#(\d+)', commit.subject + commit.body)

# Extract issue references
issues = re.findall(r'(?:fixes|closes|resolves)\s+#(\d+)', commit.body, re.IGNORECASE)

# Extract co-authors
co_authors = re.findall(r'Co-authored-by:\s+([^<]+)\s+<([^>]+)>', commit.body)

Output: Categorized commits with metadata (breaking changes, PRs, issues, authors)

Phase 4: Version Detection

Semantic Version Bump Calculation

def calculate_version_bump(commits, breaking_changes):
    """
    MAJOR: Breaking changes exist
    MINOR: Features exist (no breaking changes)
    PATCH: Only fixes exist
    """
    if breaking_changes:
        return 'MAJOR'  # x.0.0

    has_features = any(c.type == 'feat' for c in commits)
    if has_features:
        return 'MINOR'  # 0.x.0

    return 'PATCH'  # 0.0.x

# Example: v1.1.0 → v1.2.0 (MINOR bump)

Version String Construction

def build_version(last_version, bump_type):
    """
    Parse last version, apply bump, return new version
    """
    major, minor, patch = parse_semver(last_version)

    if bump_type == 'MAJOR':
        return f"{major + 1}.0.0"
    elif bump_type == 'MINOR':
        return f"{major}.{minor + 1}.0"
    else:  # PATCH
        return f"{major}.{minor}.{patch + 1}"

# Example: 1.1.0 + MINOR → 1.2.0

Output: Recommended version number and bump type

Phase 5: Changelog Generation

Format Selection

Keep a Changelog Format (default)

## [1.2.0] - 2025-10-22

### Added
- Feature A description (#123)
- Feature B description (#124)

### Fixed
- Bug A description (#125)

### Changed
- Refactoring A description (#126)

### Security
- Security update A (#127)

### Performance
- Performance improvement A (#128)

### Deprecated
- Deprecated feature A (#129)

### Removed
- Removed feature A (#130)

Conventional Format

## 1.2.0 (2025-10-22)

#### Features
* feat: add feature A (abc123)
* feat: add feature B (def456)

#### Bug Fixes
* fix: resolve bug A (ghi789)

#### Breaking Changes
* feat!: breaking change description (jkl012)

GitHub Format

## What's Changed

**New Features:**
- Add feature A by @johndoe in #123
- Add feature B by @janesmith in #124

**Bug Fixes:**
- Resolve bug A by @johndoe in #125

**Full Changelog**: v1.1.0...v1.2.0

Section Ordering

# Standard order for Keep a Changelog
section_order = [
    'Added',       # New features
    'Changed',     # Changes to existing functionality
    'Deprecated',  # Soon-to-be removed features
    'Removed',     # Removed features
    'Fixed',       # Bug fixes
    'Security',    # Security updates
    'Performance', # Performance improvements
]

Content Generation

def generate_section(category_name, commits):
    """
    Generate markdown list for a category
    """
    if not commits:
        return ""

    lines = [f"### {category_name}\n"]

    for commit in commits:
        # Format: - Subject (#PR) [by @author]
        pr_link = f"(#{commit.pr})" if commit.pr else ""
        author = f"by @{commit.author}" if commit.author else ""

        line = f"- {commit.subject} {pr_link} {author}".strip()
        lines.append(line)

    return "\n".join(lines) + "\n"

Output: Formatted changelog sections (markdown)

Phase 6: Update & Validation

Changelog File Update

Append Mode (default)

def append_to_changelog(new_version_section, changelog_path='CHANGELOG.md'):
    """
    Insert new version section at top (after header)
    """
    with open(changelog_path, 'r') as f:
        content = f.read()

    # Find insertion point (after header, before first version)
    header_end = content.find('## [')
    if header_end == -1:
        header_end = content.find('# Changelog') + len('# Changelog\n\n')

    # Insert new section
    updated = content[:header_end] + new_version_section + '\n' + content[header_end:]

    with open(changelog_path, 'w') as f:
        f.write(updated)

Overwrite Mode

def overwrite_changelog(full_changelog, changelog_path='CHANGELOG.md'):
    """
    Replace entire changelog file
    """
    with open(changelog_path, 'w') as f:
        f.write(full_changelog)

Markdown Validation

def validate_markdown(changelog_content):
    """
    Validate markdown syntax
    """
    # Check for proper header hierarchy
    assert re.match(r'^# Changelog', changelog_content), "Missing main header"

    # Check for version sections
    versions = re.findall(r'^## \[?(\d+\.\d+\.\d+)\]?', changelog_content, re.MULTILINE)
    assert len(versions) > 0, "No version sections found"

    # Check for proper list formatting
    assert not re.search(r'^\*[^ ]', changelog_content, re.MULTILINE), "Invalid list formatting"

    return True

Git Operations (optional)

# Stage changelog
git add CHANGELOG.md

# Commit changelog
git commit -m "docs: update CHANGELOG for v1.2.0"

# Create git tag
git tag -a v1.2.0 -m "Release v1.2.0"

Output: Updated CHANGELOG.md file, validation report

Workflow Summary

┌─────────────────────┐
│ 1. Context Analysis │
│  - Repository type  │
│  - Versioning scheme│
│  - Changelog location│
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ 2. Git History      │
│  - Extract commits  │
│  - Parse metadata   │
│  - Identify range   │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ 3. Categorization   │
│  - Conventional type│
│  - Breaking changes │
│  - GitHub metadata  │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ 4. Version Detection│
│  - Calculate bump   │
│  - Build version    │
│  - Validate semver  │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ 5. Generation       │
│  - Format selection │
│  - Section ordering │
│  - Content creation │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ 6. Update & Validate│
│  - Write to file    │
│  - Validate markdown│
│  - Optional git ops │
└─────────────────────┘

Error Handling

No Git Repository

Error: Not a git repository
→ Prompt user to initialize git or navigate to repository

No Commits in Range

Error: No commits found between v1.1.0 and HEAD
→ Suggest checking tag names or commit range

Invalid Version Format

Error: Cannot parse version "1.x.0"
→ Prompt user to provide valid semver format

Conflicting Changelog

Warning: CHANGELOG.md already contains entry for v1.2.0
→ Ask user: Overwrite, skip, or merge?

Next Steps

• Level 3: See EXAMPLES.md for real-world your project scenarios
• Level 4: See TROUBLESHOOTING.md for common issues and solutions

Version

1.0.0