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 — /changelog route 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 setup

Just 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 Action

Just Changesets:

pnpm add -D @changesets/cli pnpm changeset init

Add GitHub Action, document workflow

References

Detailed configurations:

• /changelog orchestrator — Full infrastructure setup

• references/changesets.md — Changesets installation, config, workflow

• references/semantic-release.md — semantic-release installation, config

• references/conventional-commits.md — Commitlint setup, Lefthook integration

"Versioning should be automatic, not an afterthought."