Changelog Generator

This skill generates and maintains changelogs following the Keep a Changelog format, integrated with Conventional Commits and Semantic Versioning.

Quick Start

When invoked, analyze git history and generate/update the changelog:

Get commits since last tag

git log $(git describe --tags --abbrev=0 2>/dev/null || echo "")..HEAD --pretty=format:"%h %s" --no-merges

Get all tags for reference

git tag --sort=-version:refname | head -10

Changelog Format (Keep a Changelog)

Changelog

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

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

Added

• New features

Changed

• Changes in existing functionality

Deprecated

• Soon-to-be removed features

Removed

• Removed features

Fixed

• Bug fixes

Security

• Vulnerability fixes

1.1.0 - 2024-01-26

Added

• New zustand-state skill for state management
• New form-validation skill with Zod + Conform integration
• New security-hardening skill for Shopify apps

Changed

• Updated shopify-developer agent with new skills
• Updated tech-lead agent with security-hardening skill

1.0.4 - 2024-01-20

Fixed

• Initial stable release

Conventional Commits Mapping

Map commit prefixes to changelog categories:

Commit Prefix Changelog Category

feat:

Added

fix:

Fixed

docs:

Changed (Documentation)

style:

Changed (Formatting)

refactor:

Changed

perf:

Changed (Performance)

test:

(Usually omitted)

build:

Changed (Build system)

ci:

(Usually omitted)

chore:

(Usually omitted)

revert:

Removed or Fixed

security: / vuln:

Security

deprecate:

Deprecated

remove: / breaking:

Removed

Generation Process

Step 1: Analyze Git History

Get commits since last release

git log v1.0.4..HEAD --pretty=format:"%H|%s|%an|%ad" --date=short

Or since a specific date

git log --since="2024-01-01" --pretty=format:"%H|%s|%an|%ad" --date=short

Step 2: Categorize Changes

Parse each commit message and categorize:

interface ChangeEntry { category: 'Added' | 'Changed' | 'Deprecated' | 'Removed' | 'Fixed' | 'Security'; description: string; commit: string; scope?: string; breaking?: boolean; }

function categorizeCommit(message: string): ChangeEntry | null { const conventionalRegex = /^(\w+)(?:(([^)]+)))?(!)?:\s*(.+)$/; const match = message.match(conventionalRegex);

if (!match) return null;

const [, type, scope, breaking, description] = match;

const categoryMap: Record<string, ChangeEntry['category']> = { feat: 'Added', fix: 'Fixed', docs: 'Changed', style: 'Changed', refactor: 'Changed', perf: 'Changed', security: 'Security', deprecate: 'Deprecated', remove: 'Removed', };

return { category: categoryMap[type] || 'Changed', description, scope, breaking: !!breaking, }; }

Step 3: Generate Markdown

function generateChangelog(entries: ChangeEntry[], version: string, date: string): string { const grouped = groupBy(entries, 'category'); const order = ['Added', 'Changed', 'Deprecated', 'Removed', 'Fixed', 'Security'];

let output = ## [${version}] - ${date}\n\n;

for (const category of order) { if (grouped[category]?.length) { output += ### ${category}\n; for (const entry of grouped[category]) { const scope = entry.scope ? **${entry.scope}:** : ''; const breaking = entry.breaking ? '⚠️ BREAKING: ' : ''; output += - ${breaking}${scope}${entry.description}\n; } output += '\n'; } }

return output; }

Version Determination

Based on changes, suggest version bump:

Change Type Version Bump Example

Breaking changes (! ) MAJOR 1.0.0 → 2.0.0

New features (feat ) MINOR 1.0.0 → 1.1.0

Bug fixes (fix ) PATCH 1.0.0 → 1.0.1

Other changes PATCH 1.0.0 → 1.0.1

function suggestVersionBump(entries: ChangeEntry[], currentVersion: string): string { const [major, minor, patch] = currentVersion.split('.').map(Number);

if (entries.some(e => e.breaking)) { return ${major + 1}.0.0; } if (entries.some(e => e.category === 'Added')) { return ${major}.${minor + 1}.0; } return ${major}.${minor}.${patch + 1}; }

Workflow Integration

Pre-release Workflow

1. Generate changelog for unreleased changes

git log $(git describe --tags --abbrev=0)..HEAD --oneline

2. Update CHANGELOG.md with new version section

3. Commit changelog

git add CHANGELOG.md git commit -m "docs: update changelog for v1.2.0"

4. Create version tag

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

5. Push with tags

git push --follow-tags

GitHub Release Integration

Generate release notes for GitHub:

Extract latest version section from CHANGELOG.md

sed -n '/^## [1.2.0]/,/^## [/p' CHANGELOG.md | head -n -1

Create GitHub release

gh release create v1.2.0 --title "v1.2.0" --notes-file release-notes.md

Output Formats

Markdown (Default)

Standard Keep a Changelog format as shown above.

JSON

{ "version": "1.1.0", "date": "2024-01-26", "changes": { "added": [ "New zustand-state skill for state management", "New form-validation skill with Zod + Conform integration" ], "changed": [ "Updated shopify-developer agent with new skills" ], "fixed": [], "security": [] } }

Release Notes (Simplified)

Release v1.1.0

Highlights

• 🎉 3 new skills added for better Shopify development

What's New

• zustand-state: State management with Zustand
• form-validation: Form validation with Zod + Conform
• security-hardening: Security best practices

Improvements

• Updated agents with new skill integrations

Full changelog: https://github.com/user/repo/blob/main/CHANGELOG.md

Best Practices

DO

• ✅ Write changelogs for humans, not machines

• ✅ Use present tense ("Add feature" not "Added feature")

• ✅ Group changes by type (Added, Changed, Fixed, etc.)

• ✅ Include links to issues/PRs when relevant

• ✅ Highlight breaking changes prominently

• ✅ Keep entries concise but descriptive

DON'T

• ❌ Include every single commit (filter noise)

• ❌ Use technical jargon without explanation

• ❌ Forget to update Unreleased section

• ❌ Mix different versions in one section

• ❌ Skip security-related changes

Commands Reference

View commits since last tag

git log $(git describe --tags --abbrev=0)..HEAD --oneline

View commits between two tags

git log v1.0.0..v1.1.0 --oneline

Get commit count by type

git log --oneline | grep -E "^[a-f0-9]+ (feat|fix|docs):" | wc -l

List all contributors since last release

git log $(git describe --tags --abbrev=0)..HEAD --format="%an" | sort -u

Generate commit list with dates

git log --since="2024-01-01" --pretty=format:"- %s (%ad)" --date=short

Example Invocations

/changelog # Generate for unreleased changes /changelog 1.2.0 # Generate for specific version /changelog --since=v1.0.0 # Changes since specific tag /changelog --format=json # Output as JSON