conventional-changelog: turning git metadata into a CHANGELOG

The gap between commit history and a readable release note

Git history is a record of work, not a document for users. A tag can point at two hundred commits, and none of them tell a reader what changed in a way they can scan. conventional-changelog exists to close that gap: the README states its purpose as "Generate a CHANGELOG from git metadata." That single sentence frames both the input and the constraint. The input is git metadata, meaning commit messages, tags and the ordering git gives you. The output is a changelog file.

The audience is narrower than the tagline suggests. This is for maintainers who already write commit messages in a structured format, most often Conventional Commits, and who want the changelog derived mechanically instead of written by hand. If your commit messages are free-form prose, the tool has little to work with, because the parsing step depends on a recognizable prefix such as a type and an optional scope. The repository README links "The Complete Guide" for readers new to Conventional Commits, which is a fair signal of the assumed starting point.

Parsing commits, filtering noise, writing sections: the package split

The mechanism is visible in the package list rather than in a single binary. The repository is a pnpm workspace, and the README's "All Packages" table names the pieces: conventional-commits-parser, conventional-commits-filter, conventional-changelog-writer, conventional-changelog-preset-loader, conventional-recommended-bump, conventional-changelog, standard-changelog, @conventional-changelog/git-client and @conventional-changelog/template.

Read that list as a pipeline. Commits come out of git, the parser turns each message into structured fields, the filter drops the ones that should not appear in a changelog, a preset supplies the rules for how types map to headings, and the writer renders the final text. The preset loader is what makes the output style pluggable: conventional-changelog-angular and conventional-changelog-conventionalcommits are separate packages precisely because they encode different conventions, and both were released at v9.4.0 and v10.4.0 respectively on 2026-08-18 according to the release list. @conventional-changelog/template, also released that day at v1.4.0, is the newer piece of that rendering path.

This split is the design decision worth noticing. You can use the parser alone, or the writer alone, without adopting the CLI. That is useful if you want changelog data in a different shape, for example a JSON feed or a custom Markdown layout. The cost is that the documentation surface is spread across many package READMEs, and the top-level README mostly points you at the documentation website and the individual package directories rather than explaining the pipeline end to end.

Installing conventional-changelog and generating a first changelog

The root package.json declares "engines": { "node": ">=22" }, so check your Node version before anything else. The README directs you to packages/conventional-changelog for the original package, and that directory's README is the place to look for the exact CLI surface. The package is published on npm under the name conventional-changelog.

A minimal install and run looks like this. The command is meant to be run inside a git repository, and the output is the changelog text printed to standard output rather than written to a file, so you can inspect it before redirecting.

npm install --save-dev conventional-changelog
npx conventional-changelog -p conventionalcommits

The -p flag selects the preset. If your project follows the Angular commit convention instead, the README lists conventional-changelog-angular as the corresponding preset package, and standard-changelog as a command line interface specifically for the angular commit format. Because the output goes to stdout, redirecting it into a file is a shell concern, not a tool flag.

The repository also ships agent skills, which is a less common inclusion. The README documents a conventional-commit-message skill that helps write Conventional Commit messages, installed through a package runner:

npx skills add conventional-changelog/conventional-changelog --skill conventional-commit-message

That skill addresses the upstream problem: a changelog generator can only be as good as the commit messages feeding it.

Where conventional-changelog stops: versioning, tagging and publishing

The most important limitation is stated by the project itself. After the getting-started section, the README recommends "considering the following high level tools for automating versioning, tagging, and CHANGELOG generation" and names commit-and-tag-version, semantic-release and simple-release-action. That is an explicit boundary. conventional-changelog generates changelog content; it does not decide your next version number, create the tag, or publish the release. conventional-recommended-bump can recommend a bump based on conventional commits, but recommendation is not the same as running the release.

A second limitation is coupling to commit discipline. The whole pipeline assumes messages parse into types and scopes. A repository with inconsistent messages will produce a changelog with entries missing, misfiled or grouped under an unhelpful heading, and no amount of configuration fixes a message that carries no structure. This is the case where the tool is simply the wrong choice: if you cannot change how your team commits, a curated release notes process will beat a generator fed on noise.

A third is the documentation layout. The top-level README is a package index plus a pointer to conventional-changelog.js.org. Details such as which flags the CLI accepts, how to configure a custom preset, and how the writer templates behave live in package-level READMEs and the website. Budget time for reading several of them rather than one.

conventional-changelog versus semantic-release

The README's own recommendation list makes the comparison concrete. semantic-release is described there as fully automating the release process from CI/CD, including version determination, changelog generation and publishing. conventional-changelog does one of those three things. The difference in approach is scope: semantic-release is a release orchestrator that happens to produce changelogs, while conventional-changelog is a changelog generator you can embed in whatever release process you already have.

That matters for control. If you want a human to review the version bump and edit the release notes before they go out, an orchestrator that publishes on merge is the wrong fit, and a generator you invoke manually or from a script is the right one. commit-and-tag-version sits between the two: the README calls it a drop-in replacement for npm's version command that handles automated version bumping, tagging and CHANGELOG generation. If your release process is already npm version plus a tag push, that is closer to a like-for-like swap than semantic-release is.

The related search terms people use around this project include conventional changelog writer, conventional changelog angular, conventional changelog conventionalcommits and conventional changelog cli. Those map onto the package split described above: the writer is the rendering layer, angular and conventionalcommits are presets, and the cli is the conventional-changelog package itself.

Maintenance, licence and what upgrading costs

The repository is not archived, and the last push was on 2026-09-21. Recent releases cluster on 2026-08-18: @conventional-changelog/template v1.4.0, conventional-changelog-conventionalcommits v10.4.0 and conventional-changelog-angular v9.4.0. Those version numbers are the practical upgrade signal, because the packages version independently. A major bump in conventional-changelog-conventionalcommits does not imply the same bump in the CLI package, and the README's package table is the place to see which packages exist before you pin anything.

Upgrade cost is mostly the preset and writer packages. If you depend on a preset's exact output shape, a major version there can change heading text or grouping, which will show up as a large diff in your CHANGELOG on the next run. Pinning versions and regenerating the changelog in a branch before merging is the cheap way to see that diff.

The licence is ISC, declared in the root package.json and in LICENSE.md. ISC is a permissive licence, similar in effect to MIT. This is a note about what the repository states, not legal advice; if your organisation has licence review requirements, run the text past whoever handles that.

Editorial conclusion

Adopt conventional-changelog if your team already writes Conventional Commits and you want a CHANGELOG file generated from git metadata rather than hand-edited, and if you are willing to run Node >= 22. Do not adopt it expecting a release manager: the README itself sends you to commit-and-tag-version, semantic-release or simple-release-action for version bumping, tagging and publishing. Before committing, check which preset matches your commit style (conventional-changelog-angular or conventional-changelog-conventionalcommits), confirm the exact CLI flags in packages/conventional-changelog, and verify that your tags and commit messages parse the way you expect.

Frequently asked questions

Official sources

1. conventional-changelog/conventional-changelog on GitHub
2. License: ISC
3. Project website
4. README
5. Releases