Changelog Automation

Auto-generate changelogs from commits.

Conventional commits

Conventional Commits is the prerequisite. Without a parseable message format, no tool can derive a meaningful changelog from history.

Format. type(scope): subject with types feat, fix, docs, refactor, test, chore.
Tooling expectation. semantic-release, conventional-changelog, and release-please all read this exact spec.
Enforcement. commitlint as a husky pre-commit hook plus a CI job rejects malformed messages before they reach main.
Onboarding cost. One short page in the repo README plus a commit template; teams pick it up inside a week.

Three tools dominate the space. Pick by how much of the release flow you want to automate, and by where the version source of truth lives.

semantic-release. Fully automated: derives the version bump from commit types, generates the changelog, and publishes the release.
conventional-changelog. Changelog generation only; useful when version bumping is manual or driven by an external tool.
release-please. Google's GitHub-native flow: opens a release PR that accumulates changes; merge it to cut the release.
Decision rule. Full automation for libraries; release-please for product apps that want a human merge gate.

The point of the tool is that release becomes a side effect of merging. Manual changelog editing disappears entirely.

On main merge. Tool computes the next version, writes the changelog entry, tags, and creates the GitHub release.
Semver mapping. BREAKING CHANGE: footer triggers MAJOR; feat triggers MINOR; fix triggers PATCH.
CHANGELOG.md. Committing the file makes history searchable from the repo without leaving the editor.
Release artefacts. npm publish, container push, or binary upload all chain off the same release event.

Engineering and customers want different changelogs. The same conventional commits feed both, but the curation differs sharply.

Internal changelog. Full detail, every commit; engineering and support read it for triage and bisection.
Customer changelog. Curated subset, plain language, grouped by feature area; refactors and chores filtered out.
One source. Both artefacts derive from conventional-changelog output; the customer version is curated downstream.
Editorial pass. Product or marketing review the customer-facing version before it ships to the changelog page.

Three failure modes turn changelog automation into noise. All three are upstream of the tool, not the tool itself.

Inconsistent commits. One non-conformant commit corrupts the whole release; commitlint must run pre-commit, not advisory.
Missing breaking-change footers. Without the explicit footer the tool ships a MINOR bump for a MAJOR change and downstream breaks unexpectedly.
Over-detailed customer changelogs. Customers do not care about refactors; surface what changed for them, hide internal churn.
No release notes review. Even with automation, a human eyeball on the auto-generated text catches the rare embarrassing line.