conventional-changelog-cli

What is conventional-changelog-cli?

The conventional-changelog-cli package is a command-line tool that helps automate the process of generating changelogs based on conventional commit messages. It follows the Conventional Commits specification, which is a standardized way of writing commit messages that makes it easier to create automated tools for versioning and changelog generation.

What are conventional-changelog-cli's main functionalities?

Generate Changelog

This command generates a changelog based on the Angular preset and writes it to the CHANGELOG.md file. The '-s' flag ensures that the file is saved.

npx conventional-changelog -p angular -i CHANGELOG.md -s

Generate Changelog for a Specific Release

This command generates a changelog for the last two releases based on the Angular preset and writes it to the CHANGELOG.md file.

npx conventional-changelog -p angular -i CHANGELOG.md -s -r 2

Generate Changelog for a Specific Commit Range

This command generates a changelog for commits in a specific path or range and writes it to the CHANGELOG.md file.

npx conventional-changelog -p angular -i CHANGELOG.md -s --commit-path ./path/to/commits

Other packages similar to conventional-changelog-cli

standard-version

standard-version is a tool for versioning and changelog generation based on conventional commit messages. It automates the process of version bumping, changelog generation, and Git tagging. Compared to conventional-changelog-cli, standard-version provides a more integrated approach to version management and release automation.

semantic-release

semantic-release automates the whole package release workflow including determining the next version number, generating the changelog, and publishing the package. It uses the commit messages to determine the type of changes in the codebase. Compared to conventional-changelog-cli, semantic-release offers a more comprehensive solution for continuous delivery and release management.

release-it

release-it is a versatile CLI tool for automating versioning and package publishing. It supports conventional changelog generation and can be extended with plugins for additional functionality. Compared to conventional-changelog-cli, release-it provides a more flexible and extensible approach to release automation.

README

conventional-changelog-cli

Generate a changelog from git metadata

Changelog?

Note You don't have to use the angular commit convention. For the best result of the tool to tokenize you commit and produce flexible output, it's recommended to use a commit convention.

Quick start

$ npm install -g conventional-changelog-cli
$ cd my-project
$ conventional-changelog -p angular -i CHANGELOG.md -s

This will not overwrite any previous changelog. The above generates a changelog based on commits since the last semver tag that match the pattern of a "Feature", "Fix", "Performance Improvement" or "Breaking Changes".

If you first time use this tool and want to generate all previous changelog, you could do

$ conventional-changelog -p angular -i CHANGELOG.md -s -r 0

This will overwrite any previous changelog if exist.

All available command line parameters can be listed using CLI: conventional-changelog --help.

Hint: You can alias your command or add it to your package.json. EG: "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0".

To fully customize the tool, please checkout conventional-changelog and conventional-changelog-core docs. You can find more details there. Note: config here can work with preset, which is different than options.config in conventional-changelog.

Example output

• https://github.com/ajoslin/conventional-changelog/blob/master/CHANGELOG.md
• https://github.com/karma-runner/karma/blob/master/CHANGELOG.md
• https://github.com/btford/grunt-conventional-changelog/blob/master/CHANGELOG.md

Recommended workflow

1. Make changes
2. Commit those changes
3. Make sure Travis turns green
4. Bump version in package.json
5. conventionalChangelog
6. Commit package.json and CHANGELOG.md files
7. Tag
8. Push

The reason why you should commit and tag after conventionalChangelog is that the CHANGELOG should be included in the new release, hence gitRawCommitsOpts.from defaults to the latest semver tag.

With npm version

Using the npm scripts to our advantage with the following hooks:

{
  "scripts": {
    "version": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0 && git add CHANGELOG.md"
  }
}

You could follow the following workflow

1. Make changes
2. Commit those changes
3. Pull all the tags
4. Run the npm version [path|minor|major] command
5. Push

You could optionally add a preversion script to package your project or running a full suit of test. And a postversion script to clean your system and push your release and tags.

By adding a .npmrc you could also automate your commit message and set your tag prefix as such:

tag-version-prefix=""
message="chore(release): %s :tada:"

Why

• Used by AngularJS, JSHint and related projects.
• Easy fully automate changelog generation. You could still add more points on top of it.
• Ignoring reverted commits, templating with handlebars.js and links to references, etc. Open an issue if you want more reasonable features.
• Intelligently setup defaults but yet fully configurable with presets of popular projects.
• Everything internally or externally is pluggable.
• A lot of tests and actively maintained.

Problems with github-changelog-generator or similar projects

• Opinionated on how to write commits, issues or PRs.
• No or partially support reference links.
• Not system agnostic. Only support GitHub.
• No template support. The output is mostly certain format of markdown.
• No presets of popular commit message conventions.
• Not modularized. Over the years modularization is proven to be the best practice.
• No tests or coverage is too low. Program might be buggy.
• Do not read your project's environment.
• No or few task runner or build tool integrations.

Related

• conventional-changelog - API of this module
• standard-changelog - Similar to this module but only with angular convention
• conventional-github-releaser - Make a new GitHub release from git metadata
• conventional-recommended-bump - Get a recommended version bump based on conventional commits
• conventional-commits-detector - Detect what commit message convention your repository is using
• commitizen - Simple commit conventions for internet citizens.
• angular-precommit - Pre commit with angular conventions
• commitlint - Lint commit messages

License

MIT © Steve Mao