Enhanced changelog generation with semantic versioning, auto-categorization, and release notes. Parses conventional commits, determines version bump (MAJOR.MINOR.PATCH), categorizes changes by type, generates CHANGELOG.md updates, and creates GitHub release notes. Use before releases or on PR merge to automate version management.
Enhanced changelog generation with semantic versioning, auto-categorization, and release notes. Parses conventional commits, determines version bump (MAJOR.MINOR.PATCH), categorizes changes by type, generates CHANGELOG.md updates, and creates GitHub release notes. Use before releases or on PR merge to automate version management.
Automatically generate CHANGELOG.md updates and GitHub release notes from conventional commits with semantic versioning analysis. This skill provides intelligent version management and changelog generation that surpasses Auto Claude's capabilities.
Integration Ready - Seamless integration with git workflow
Conventional Commit Format
PopKit follows conventional commit format:
<type>(<scope>): <subject>
<body>
<footer>
Commit Types
Type
Description
Version Bump
feat
New feature
MINOR (1.0.0 → 1.1.0)
fix
Bug fix
PATCH (1.0.0 → 1.0.1)
perf
Performance improvement
PATCH
refactor
Code refactoring
PATCH
docs
Documentation only
PATCH
test
Test additions/updates
PATCH
chore
Maintenance tasks
PATCH
ci
CI/CD changes
PATCH
build
Build system changes
PATCH
style
Formatting, no code change
PATCH
BREAKING CHANGE
Breaking change
MAJOR (1.0.0 → 2.0.0)
Version Bump Rules
The changelog generator automatically determines the appropriate version bump:
- commit body footer
- Incompatible API changes
- Major architectural changes
- feat: commits
- New features added
- Backward-compatible functionality
- fix: commits
- Bug fixes
- Performance improvements
- Refactoring
- Documentation updates
# MAJOR bump (1.0.0 → 2.0.0)
Any
with
"BREAKING CHANGE"
in
or
# MINOR bump (1.0.0 → 1.1.0)
# PATCH bump (1.0.0 → 1.0.1)
Usage
Automatic (Recommended)
Changelog is automatically updated when:
Before PR creation (/popkit:git pr)
Analyzes commits since last release
Generates changelog entry
Updates CHANGELOG.md
Includes changelog in PR description
Before release (/popkit:git release)
Determines version bump automatically
Updates CHANGELOG.md with new version
Generates GitHub release notes
Creates git tag
On PR merge (via hook)
Updates changelog for merged changes
Prepares for next release
Manual
# Preview changelog for next version (auto-determined)
/popkit:git changelog --preview
# Generate changelog with specific version
/popkit:git changelog --version 1.1.0
# Generate since specific tag
/popkit:git changelog --since v1.0.0
# Generate GitHub release notes
/popkit:git changelog --release
# Auto-determine version bump
/popkit:git changelog --auto
# Update CHANGELOG.md
/popkit:git changelog --update
Python CLI
# From project rootcd /path/to/project
# Preview next version
python packages/shared-py/popkit_shared/utils/changelog_generator.py --preview
# Auto-determine version and update CHANGELOG.md
python packages/shared-py/popkit_shared/utils/changelog_generator.py --auto --update
# Generate GitHub release notes
python packages/shared-py/popkit_shared/utils/changelog_generator.py --release
# Get version bump analysis as JSON
python packages/shared-py/popkit_shared/utils/changelog_generator.py --json
Output Examples
CHANGELOG.md Entry
## [1.1.0] - 2026-01-08### ✨ Features-**changelog-automation**: Enhanced changelog generation with semantic versioning (#27)
-**git-workflow**: Automatic changelog updates on PR creation and merge (#28)
-**release-notes**: Auto-generate GitHub release notes from commits (#29)
### 🐛 Bug Fixes-**git**: Fix merge conflict detection in subdirectories (#30)
-**hooks**: Correct Windows path handling in pre-commit hook (#31)
### 💥 BREAKING CHANGES-**api**: Change authentication endpoint from /auth to /api/auth
- Migration: Update all API calls to use new endpoint
- See migration guide: docs/migrations/v1.1.0.md
### 📚 Documentation-**readme**: Update installation instructions with new requirements
-**skills**: Add usage examples for changelog automation
### ⚡ Performance-**complexity-analyzer**: Reduce analysis time by 40% with caching
### 🔧 Chores-**deps**: Update dependencies to latest versions
-**ci**: Add automated changelog generation to CI pipeline
GitHub Release Notes
# PopKit 1.1.0 - Enhanced Changelog Automation## 🎉 What's New### Changelog Automation
Enhanced changelog generation with semantic versioning, auto-categorization, and intelligent version bump detection. Simply commit using conventional format and get professional changelogs automatically.
(#27)
### Git Workflow Integration
Automatic changelog updates on PR creation and merge. No more manual changelog maintenance - PopKit handles it all for you.
(#28)
### Release Notes Generation
Auto-generate GitHub release notes from commits with proper formatting, breaking change warnings, and migration guides.
(#29)
## 💥 Breaking Changes### Change authentication endpoint from /auth to /api/auth**Migration:**- Update all API calls to use new endpoint
- See migration guide: docs/migrations/v1.1.0.md
## 🐛 Bug Fixes- Fix merge conflict detection in subdirectories (#30)
- Correct Windows path handling in pre-commit hook (#31)
## 📊 Statistics-**Features Added:** 3
-**Bug Fixes:** 2
-**Total Commits:** 12
-**Issues Closed:** 5
## 🔗 Links-**Full Changelog:** [CHANGELOG.md](CHANGELOG.md#110---2026-01-08)
-**Issues Closed:** #27, #28, #29, #30, #31
---
**Install:**`/plugin install popkit-suite@popkit-claude`**Upgrade:**`/plugin update popkit-suite`
Integration with Git Workflow
PR Creation Flow
# When creating PR with /popkit:git pr:
1. Detect commits since last release
2. Analyze commit types
3. Determine version bump (if release PR)
4. Generate changelog entry
5. Update CHANGELOG.md
6. Include changelog in PR description
7. Create PR
Release Flow
# When creating release with /popkit:git release:
1. Get commits since last version tag
2. Determine semantic version bump
3. Calculate next version
4. Generate changelog entry
5. Update CHANGELOG.md
6. Generate GitHub release notes
7. Save release notes file
8. Create git tag with version
9. Create GitHub release with notes
10. Publish release
Breaking Change Format
When introducing breaking changes, use this format:
feat(api): Change authentication endpoint
Move authentication from /auth to /api/auth for consistency with REST API structure.
BREAKING CHANGE: Authentication endpoint changed from /auth to /api/auth
Migration: Update all API calls to use new endpoint
See migration guide: docs/migrations/v1.1.0.md
The changelog generator will:
Detect "BREAKING CHANGE" in footer
Categorize as MAJOR version bump
Extract migration notes from footer
Highlight in both CHANGELOG.md and release notes
Validation
The changelog generator validates:
Conventional commit format - Ensures commits follow type(scope): description format
Version bump logic - Correctly determines MAJOR/MINOR/PATCH
Breaking change detection - Identifies "BREAKING CHANGE" in footer
Issue reference extraction - Finds all #N references
Categorization - Groups commits by type with proper priority
Best Practices
Use conventional commits - Always format commits as type(scope): description
Include issue references - Add (#123) to link commits to issues
Document breaking changes - Use BREAKING CHANGE footer with migration notes
Scope your commits - Use meaningful scopes like api, ui, core
Write clear descriptions - Make it easy to understand the change
Git command integration - Add changelog flags to /popkit:git pr and /popkit:git release
Pre-commit hook - Validate conventional commit format
Automated tests - Test version bump logic and changelog generation
GitHub Actions - Auto-update changelog on PR merge
Visual reports - Generate HTML changelog reports
Strategic Value: This quick win from Issue #27 delivers immediate time savings while establishing PopKit as superior to Auto Claude in changelog automation quality and intelligence.
