What is Conventional Changelog?
Last reviewed May 28, 2026
Conventional Changelog is the open-source ecosystem of tools that automatically generates a changelog from a commit history written using the Conventional Commits specification. The flagship package (`conventional-changelog` on npm) reads your git log, parses `feat:`, `fix:`, and `BREAKING CHANGE:` prefixes, and produces or updates a `CHANGELOG.md` file grouped by category. The same project also powers semantic-release and other CI-integrated tools that bump versions, tag releases, and publish to package registries without human input.
Example
A Node.js project with a commit history of feat: add OAuth login, fix: handle expired tokens, and BREAKING CHANGE: drop Node 16 can run npx conventional-changelog -p angular -i CHANGELOG.md -s to update the changelog file automatically — grouped by category, with each entry linked back to the commit. Paired with semantic-release, the same data also triggers a version bump (here, a major because of the breaking change) and publishes the new release.
Why it matters
Conventional Changelog operationalizes Conventional Commits — turning the commit discipline into an automated changelog pipeline. For library and SDK maintainers shipping to npm, PyPI, crates.io, or similar package registries, the combination eliminates manual changelog work entirely while keeping the output consistent across every release. For SaaS teams, the same tooling generates the engineering-flavored release log; tools like Herald layer the customer-flavored release on top.
More context
The Conventional Changelog ecosystem is a stack of tools that all consume the same input (commits formatted per Conventional Commits) and produce different outputs:
conventional-changelog— the foundational CLI and library. Reads git history and generates aCHANGELOG.md. Supports configurable presets (Angular, Atom, ESLint, JSHint, jQuery, etc.) that determine how categories are named and formatted.semantic-release— fully automated version management and package publishing. Reads commits, determines the next version per semver, generates release notes, tags the commit, publishes to npm (or other registries), and updates the changelog — all from CI on every merge to main.commitizen— interactive prompt that walks developers through writing a Conventional Commit message. Reduces the friction of adopting the convention by hand-typing.commitlint— CI lint that fails the build if a commit doesn't match the Conventional Commits spec. Enforces the convention without relying on goodwill.
The standard adoption path is: install commitlint with a git hook → optionally install commitizen for interactive prompts → install conventional-changelog or semantic-release in CI → never write a changelog entry by hand again.
The friction is upfront, not ongoing: the team has to agree to write commits the convention way, which feels like extra discipline at first but becomes muscle memory in a sprint or two. The payoff compounds — every release after that is one CI run instead of a manual triage of every PR since the last release.
For SaaS teams shipping a customer-facing changelog (where the audience is users, not other engineers), the engineering-flavored output of conventional-changelog is useful but not sufficient — customers don't want to read feat(api): add /v2/users endpoint with cursor pagination. Tools like Herald take the same underlying GitHub PR data (and the merged PR titles + descriptions, which usually mirror commit messages on PR-squash-merge workflows) and draft a separate customer-flavored release alongside the engineering-flavored one. See Herald and GitHub Releases for the bidirectional pattern.
Related terms
Want to go deeper? Read Herald and GitHub Releases — when to use each.