Description
Automate changelog generation using conventional commits or GitHub releases to reduce manual maintenance.
Current State
CHANGELOG.md is manually maintained, which requires:
- Remembering to update it with each change
- Consistent formatting across versions
- Time and effort from maintainers
Proposed Solution
Option 1: Conventional Changelog (Recommended)
Use standard-version or semantic-release to auto-generate changelog from commit messages.
Setup:
npm install --save-dev standard-version
Usage:
npm run release
# Automatically:
# 1. Bumps version in pom.xml
# 2. Updates CHANGELOG.md
# 3. Creates git tag
# 4. Commits changes
Commit Format Required:
feat: add new StringUtil method
fix: correct NPE in ClassUtil
docs: update README
refactor: simplify PropertyUtil
test: add tests for SoapRecord
chore: update dependencies
BREAKING CHANGE: removed deprecated methods
Option 2: GitHub Release Notes
Use GitHub's auto-generated release notes:
In GitHub Actions:
- name: Create GitHub Release
uses: ncipollo/release-action@v1
with:
tag: ${{ github.ref }}
generateReleaseNotes: true
token: ${{ secrets.GITHUB_TOKEN }}Benefits:
- Auto-generates from PR titles
- No additional tools needed
- Links to PRs and commits
Option 3: git-cliff
Modern Rust-based changelog generator:
# cliff.toml
[changelog]
header = """
# Changelog
All notable changes to this project will be documented in this file.
"""
[git]
commit_parsers = [
{ message = "^feat", group = "Features" },
{ message = "^fix", group = "Bug Fixes" },
{ message = "^doc", group = "Documentation" },
{ message = "^perf", group = "Performance" },
{ message = "^refactor", group = "Refactoring" },
{ message = "^test", group = "Testing" },
]Comparison
| Tool |
Pros |
Cons |
| standard-version |
Mature, npm ecosystem |
Requires Node.js |
| GitHub Releases |
No setup, GitHub-native |
Less detailed |
| git-cliff |
Fast, configurable |
Newer tool |
| Manual |
Full control |
Time-consuming |
Recommended Workflow
- Use conventional commits for all changes
- Auto-generate changelog on release
- Keep manual CHANGELOG.md for major versions
- GitHub Releases for per-version notes
Integration with Current Workflow
The current workflow already:
- ✅ Auto-bumps version
- ✅ Creates git tags
- ✅ Commits with
[ci skip]
Just need to add:
- ⬜ Changelog generation step
- ⬜ GitHub release creation
Updated Workflow
- name: Generate Changelog
run: |
# Install git-cliff or standard-version
# Generate CHANGELOG.md
# Commit to repo
- name: Create GitHub Release
uses: ncipollo/release-action@v1
with:
tag: ${{ steps.version.outputs.new_version }}
generateReleaseNotes: true
bodyFile: RELEASE_NOTES.mdMigration Plan
- Phase 1: Start using conventional commits (no breaking changes)
- Phase 2: Add changelog generation to CI/CD
- Phase 3: Archive old manual CHANGELOG.md entries
- Phase 4: Fully automated releases
Files to Modify
.github/workflows/main.yml (add changelog step)package.json (if using npm tools)cliff.toml (if using git-cliff)
Priority
Low - Nice to have for reducing maintenance burden
References
Description
Automate changelog generation using conventional commits or GitHub releases to reduce manual maintenance.
Current State
CHANGELOG.mdis manually maintained, which requires:Proposed Solution
Option 1: Conventional Changelog (Recommended)
Use
standard-versionorsemantic-releaseto auto-generate changelog from commit messages.Setup:
Usage:
Commit Format Required:
Option 2: GitHub Release Notes
Use GitHub's auto-generated release notes:
In GitHub Actions:
Benefits:
Option 3: git-cliff
Modern Rust-based changelog generator:
Comparison
Recommended Workflow
Integration with Current Workflow
The current workflow already:
[ci skip]Just need to add:
Updated Workflow
Migration Plan
Files to Modify
.github/workflows/main.yml(add changelog step)package.json(if using npm tools)cliff.toml(if using git-cliff)Priority
Low - Nice to have for reducing maintenance burden
References