Automating Versioning and Changelogs with Conventional Commits
conventional-changelog-angular, conventional-changelog-cli, and standard-version are tools designed to automate semantic versioning and changelog generation based on commit message standards. conventional-changelog-angular defines the specific rules for parsing Angular-style commit messages. conventional-changelog-cli is a command-line tool that generates changelog files using those rules. standard-version is a higher-level utility that combines version bumping, changelog generation, and git tagging into a single workflow. Together, they help teams maintain clear release history and consistent version numbers without manual effort.
Npm Package Weekly Downloads Trend
Github Stars Ranking
Stat Detail
Automating Versioning and Changelogs with Conventional Commits
Managing release history and version numbers manually is error-prone and time-consuming. The conventional-changelog ecosystem offers tools to automate this based on commit messages. While conventional-changelog-angular, conventional-changelog-cli, and standard-version are often used together, they serve different layers of the release process. Let's break down how they differ and when to use each.
🛠️ Scope of Work: Config vs. Tool vs. Workflow
conventional-changelog-angular is a configuration preset.
- It defines the rules for parsing commit messages.
- It does not run on its own — it supports other tools.
// conventional-changelog-angular: Used as a config preset
const config = {
preset: 'angular',
// Or explicitly require the package
config: require('conventional-changelog-angular')
};
conventional-changelog-cli is a generation tool.
- It reads git history and writes a changelog file.
- It does not bump versions or commit changes.
# conventional-changelog-cli: Generate changelog only
npx conventional-changelog-cli -p angular -i CHANGELOG.md -s
standard-version is a complete workflow utility.
- It bumps the version, generates the changelog, and commits tags.
- It replaces
npm versionfor local releases.
# standard-version: Full release workflow
npx standard-version
⚙️ Configuration and Customization
How you configure these tools depends on how much control you need over the output.
conventional-changelog-angular requires no setup if used as a string preset.
- For custom rules, you extend the preset object.
- Useful when building custom release scripts.
// conventional-changelog-angular: Customizing rules
module.exports = {
parserOpts: {
headerPattern: /^(\w*)(?:\((.*)\))?\:(.*)$/,
headerCorrespondence: ['type', 'scope', 'subject']
}
};
conventional-changelog-cli accepts flags for input and output control.
- You specify the preset, input file, and inplace editing.
- Good for scripting specific changelog updates.
# conventional-changelog-cli: Custom config via flags
npx conventional-changelog-cli -p angular -i CHANGELOG.md -s -r 0
standard-version uses a .versionrc file for complex setups.
- You can define skip steps or custom scripts.
- Ideal for projects needing lifecycle hooks.
// standard-version: .versionrc configuration
{
"types": [
{ "type": "feat", "section": "Features" },
{ "type": "fix", "section": "Bug Fixes" }
],
"skip": {
"tag": true
}
}
📦 Git and Version Management
The biggest difference lies in how these tools interact with git and version numbers.
conventional-changelog-angular does not touch git.
- It is purely a logic package for parsing text.
- You must handle git operations yourself.
// conventional-changelog-angular: No git interaction
// Used internally to parse commit messages
const commit = { hash: 'abc123', message: 'feat: add login' };
// Parser logic applied here
conventional-changelog-cli reads git history but does not write commits.
- It generates the
CHANGELOG.mdfile only. - You must run
git addandgit commitseparately.
# conventional-changelog-cli: Manual git steps required
npx conventional-changelog-cli -p angular -i CHANGELOG.md -s
git add CHANGELOG.md
git commit -m "docs: update changelog"
standard-version handles git commits and tags automatically.
- It creates a version commit and a git tag.
- Reduces manual steps for local releases.
# standard-version: Automatic git management
npx standard-version
# Automatically runs: git add, git commit, git tag
🔄 CI/CD Integration
Integration into continuous deployment pipelines varies by tool.
conventional-changelog-angular is a dependency in your pipeline script.
- Imported by Node.js scripts in CI.
- Provides the logic for version determination.
// conventional-changelog-angular: In CI script
const conventionalChangelog = require('conventional-changelog');
const config = require('conventional-changelog-angular');
// Used to calculate next version
conventional-changelog-cli runs as a step in your build job.
- Useful if you only need to update docs before deploy.
- Does not trigger deployment itself.
# conventional-changelog-cli: In GitHub Actions
- name: Generate Changelog
run: npx conventional-changelog-cli -p angular -i CHANGELOG.md -s
standard-version is often replaced by semantic-release in full CI/CD.
- It is designed for local manual releases.
- Can be used in CI but requires git credentials.
# standard-version: In CI (less common for full auto)
- name: Release
run: npx standard-version
env:
GIT_AUTHOR_NAME: "CI Bot"
📊 Summary Table
| Feature | conventional-changelog-angular | conventional-changelog-cli | standard-version |
|---|---|---|---|
| Primary Role | Config Preset | Changelog Generator | Release Workflow |
| Bumps Version | ❌ No | ❌ No | ✅ Yes |
| Commits Git | ❌ No | ❌ No | ✅ Yes |
| Generates Changelog | ❌ No (Provides rules) | ✅ Yes | ✅ Yes |
| Best For | Custom Scripts | Modular Pipelines | Local Manual Releases |
💡 The Big Picture
conventional-changelog-angular is the rulebook 📖 — it defines what a feat or fix means. You rarely use it alone, but it powers the other tools.
conventional-changelog-cli is the writer ✍️ — it drafts the changelog based on the rules. Use this if you want to control versioning separately.
standard-version is the project manager 📋 — it handles the version number, the changelog, and the git commit in one go. It is excellent for local workflows where a developer triggers the release.
Final Thought: For fully automated CI/CD pipelines, many teams now prefer semantic-release over standard-version. However, if you need manual control over when a release happens, standard-version remains a solid choice. Use conventional-changelog-cli if you only need to update documentation without changing versions.
How to Choose: conventional-changelog-angular vs conventional-changelog-cli vs standard-version
- conventional-changelog-angular:
Choose
conventional-changelog-angularwhen you need the specific rule set for parsing Angular-style commit messages within a larger tooling setup. It is not a standalone tool but a dependency that defines how commit types likefeatorfixmap to version bumps. Use this if you are building a custom release script or configuring another tool that requires a preset. It is essential for enforcing consistency in commit history across teams using the Conventional Commits specification. - conventional-changelog-cli:
Choose
conventional-changelog-cliwhen you only need to generate or update a changelog file without automatically bumping versions or managing git tags. It offers granular control over the changelog generation process and fits well into custom CI/CD pipelines. This tool is ideal if you handle version numbering separately or need to regenerate history without altering git state. It works best for projects that require a modular approach to release automation. - standard-version:
Choose
standard-versionwhen you want a single command to handle version bumping, changelog generation, and git committing locally. It replaces the standardnpm versionworkflow and is perfect for teams that prefer manual release triggers over fully automated CI/CD. This package is suitable for libraries or apps where a developer explicitly cuts a release rather than relying on continuous deployment. Note that for fully automated CI/CD pipelines, many teams now prefersemantic-release, butstandard-versionremains robust for local workflows.
Popular Comparisons
README for conventional-changelog-angular
conventional-changelog-angular
conventional-changelog angular preset.
Issues with the convention itself should be reported on the Angular issue tracker.
Install
# pnpm
pnpm add -D conventional-changelog-angular
# yarn
yarn add -D conventional-changelog-angular
# npm
npm i -D conventional-changelog-angular
Usage
Use with conventional-changelog by passing the preset name with -p:
conventional-changelog -p angular
Documentation
For the commit convention details and preset options, visit the documentation website.