conventional-changelog

What is conventional-changelog?

The conventional-changelog npm package automates the generation of changelogs based on commit messages that follow the Conventional Commits specification. This tool is widely used to maintain a clear, readable history of project changes which can be easily communicated to other developers and users.

What are conventional-changelog's main functionalities?

Generate changelog

This code demonstrates how to generate a changelog using the Angular preset. The changelog will be written to a file named 'CHANGELOG.md'.

const conventionalChangelog = require('conventional-changelog');
const fs = require('fs');
const changelogStream = conventionalChangelog({ preset: 'angular' });
changelogStream.pipe(fs.createWriteStream('CHANGELOG.md'));

Create a release

This code snippet shows how to automatically determine the semantic version bump based on commit messages. It uses the Angular preset to recommend a bump and then uses npm to update the project version accordingly.

const conventionalRecommendedBump = require('conventional-recommended-bump');
const exec = require('child_process').exec;
conventionalRecommendedBump({ preset: 'angular' }, (error, recommendation) => {
  exec(`npm version ${recommendation.releaseType}`, (error, stdout, stderr) => {
    console.log('Version bumped to', stdout);
  });
});

Other packages similar to conventional-changelog

standard-version

standard-version is a utility for versioning using semver and CHANGELOG generation powered by Conventional Commits. It automates versioning and changelog generation but with a simpler setup compared to conventional-changelog, integrating these steps into a single command.

semantic-release

semantic-release automates the whole package release workflow including determining the next version number, generating the release notes, and publishing the package. This tool provides a more comprehensive solution compared to conventional-changelog by handling the entire release process in a CI/CD environment.

lerna

Lerna is a tool for managing JavaScript projects with multiple packages, known as monorepos. While it includes functionality for generating changelogs similar to conventional-changelog, its primary focus is on managing dependencies and publishing multiple packages from the same repository.

README

Generate a changelog from git metadata

Why

• Used by AngularJS and related projects.
• Everything internally or externally is Pluggable.
• High performant. It doesn't spawn any extra child process to fetch data.
• Fully configurable. There are several presets that you can use if you just want to use the same conventions. But it is also possible to configure if you want to go down to the nth degree.
• Task runner integrations.
• Actively maintained.

Install

$ npm install conventional-changelog

Adapted from code originally written by @vojtajina and @btford in grunt-conventional-changelog.

Note: As 0.1.x this module is rewritten and so the API is not backward compatible. If you are still using 0.0.x please checkout the README in your downloaded package or dig through the old tags.

Synopsis of Conventions

Example output

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

Usage

var conventionalChangelog = require('conventional-changelog');

conventionalChangelog({
  preset: 'angular'
})
  .pipe(process.stdout);

API

conventionalChangelog([options, [context, [gitRawCommitsOpts, [parserOpts, [writerOpts]]]]])

Returns a readable stream.

options

preset

Type: string Possible values: 'angular', 'jquery'

A set of options of a popular project.

pkg

Type: string Default: 'package.json'

The location of your "package.json".

append

Type: boolean Default: false

Should the log be appended.

allBlocks

Type: boolean Default: false

Set to true if you want to generate all blocks of the log. false if you just want to generate the current one.

warn

Type: function Default: function() {}

A warn function. EG: grunt.verbose.writeln

transform

Type: object Default: through.obj()

A transform stream that applies after the parser and before the writer.

context

See the conventional-commits-writer docs.

gitRawCommitsOpts

See the git-raw-commits docs.

parserOpts

See the conventional-commits-parser docs.

writerOpts

See the conventional-commits-writer docs.

CLI

$ npm install -g conventional-changelog

$ conventional-changelog --help

  Generate a changelog from git metadata

  Usage
    conventional-changelog

  Example
    conventional-changelog -i CHANGELOG.md --overwrite

  Options
    -i, --infile              Read the CHANGELOG from this file.
    -o, --outfile             Write the CHANGELOG to this file. If unspecified, it prints to stdout
    -w, --overwrite           Overwrite the infile
    -p, --preset              Name of the preset you want to use
    -k, --pkg                 A filepath of where your package.json is located
    -a, --append              Should the generated block be appended
    -b, --all-blocks          Generate all blocks
    -v, --verbose             Verbose output
    -c, --context             A filepath of a javascript that is used to define template variables
    --git-raw-commits-opts    A filepath of a javascript that is used to define git-raw-commits options
    --parser-opts             A filepath of a javascript that is used to define conventional-commits-parser options
    --writer-opts             A filepath of a javascript that is used to define conventional-commits-writer options

Related

• conventional-recommended-bump - Get a recommended version bump based on conventional commits

License

BSD