Changelog Automation
Manual changelog maintenance is error-prone. Automate version bumping, changelog updates, and release notes.
For full infrastructure setup, use /changelog — the orchestrator skill that installs semantic-release, LLM synthesis, and a public changelog page.Philosophy
Two proven approaches:
- semantic-release: Commit-based workflow using conventional commits (recommended for web apps)
- Changesets: PR-based workflow with explicit change declarations (best for npm monorepos)
Both enforce Semantic Versioning and integrate with CI/CD.
When to Use What
| Scenario | Tool |
|---|---|
| Web app (every merge is a release) | semantic-release |
| Publishing npm packages | Changesets or semantic-release |
| Monorepo with multiple npm packages | Changesets |
| Want maximum automation | semantic-release |
| Want explicit control over releases | Changesets |
Default recommendation: semantic-release for web apps. Every merge to main deploys to production anyway — let the release happen automatically.
Semantic Versioning (SemVer)
MAJOR.MINOR.PATCH:
- MAJOR (1.0.0 → 2.0.0): Breaking changes
- MINOR (1.0.0 → 1.1.0): New features, backward-compatible
- PATCH (1.0.0 → 1.0.1): Bug fixes
Comparison
| Feature | semantic-release | Changesets |
|---|---|---|
| Best for | Web apps, single packages | npm monorepos |
| Workflow | Commit-based (automatic) | PR-based (explicit files) |
| Automation | Fully automated | Semi-automated |
| Control | Low (commits drive releases) | High |
| Team discipline | High (strict commits) | Low |
| Monorepo support | Requires plugins | Excellent |
The Full Stack
For complete release infrastructure (not just versioning), /changelog installs:
- semantic-release — Automatic version bumping from conventional commits
- commitlint + Lefthook — Enforce commit message format
- GitHub Actions — CI workflow for releases
- Gemini 3 Flash synthesis — Transform technical notes to user-friendly language
- Public changelog page —
/changelogroute with RSS feed
Best Practices
Do
- Choose one approach, not both
- Enforce conventional commits (commitlint)
- Automate with GitHub Actions
- Generate user-friendly release notes (LLM synthesis)
- Tag releases in git
- Provide a public changelog page
Don't
- Manually edit CHANGELOG.md
- Skip commit message enforcement
- Ignore breaking changes
- Publish without CI
- Forget to build before publish
- Hide release notes behind auth
Quick Setup
Full infrastructure (recommended):
/changelog setupJust semantic-release:
pnpm add -D semantic-release @semantic-release/git @semantic-release/changelog
pnpm add -D @commitlint/cli @commitlint/config-conventional
# Configure .releaserc.js, commitlint, GitHub ActionJust Changesets:
pnpm add -D @changesets/cli
pnpm changeset init
# Add GitHub Action, document workflowReferences
Detailed configurations:
/changelogorchestrator — Full infrastructure setupreferences/changesets.md— Changesets installation, config, workflowreferences/semantic-release.md— semantic-release installation, configreferences/conventional-commits.md— Commitlint setup, Lefthook integration
"Versioning should be automatic, not an afterthought."