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

conventional-changelog

$ npm install conventional-changelog

Generate a changelog from git metadata, using the AngularJS commit conventions.

• Synopsis of Conventions in CONVENTIONS.md
• Full Convention Spec on Google Docs

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

Example output

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

Roadmap

• Make it return a stream
• Add a proper command line interface
• Add configurable subjects & sections
• Split up this repo into smaller modules #22

Documentation

Simple usage:

require('conventional-changelog')({
  repository: 'https://github.com/joyent/node',
  version: require('./package.json').version
}, function(err, log) {
  console.log('Here is your changelog!', log);
});

changelog(options, callback)

By default, calls the callback with a string containing a changelog from the previous tag to HEAD, using pkg.version, prepended to existing CHANGELOG.md (if it exists).

callback is the second parameter, and takes two parameters: (err, log). log is a string containing the newly generated changelog, and err is either an error or null.

options is the first parameter, an object. The following fields are available:

The Most Important Options

• version {string} - The version to be written to the changelog. For example, {version: "1.0.1"}. Defaults to the version found in package.json. See pkg to configure the path of package.json.

• subtitle {string} - A string to display after the version title in the changelog. For example, it will show '## 1.0.0 "Super Version"' if codename '"Super Version"' is given. By default, it's blank.

• repository {string} - If this is provided, allows issues and commit hashes to be linked to the actual commit. Usually used with github repositories. For example, {repository: 'http://github.com/joyent/node'}. Defaults to "normalized" repository.url found in package.json. See pkg to configure the path of package.json.

• pkg {string} - The path of package.json. Defaults to ./package.json.

• from {string} - Which commit the changelog should start at. By default, uses previous tag, or if no previous tag the first commit.

• to {string} - Which commit the changelog should end at. By default, uses HEAD.

• file {string} - Which file to read the current changelog from and prepend the new changelog's contents to. By default, uses 'CHANGELOG.md'.

The "I really want to get crazy" Options

• versionText {function(version, subtitle)} - What to use for the title of a major version in the changelog. Defaults to '## ' + version + ' ' + subtitle.

• patchVersionText {function(version, subtitle)} - What to use for the title of a patch version in the changelog. Defaults to '### ' + version + ' ' + subtitle.

• commitLink {function(commitHash)} - If repository is provided, this function will be used to link to commits. By default, returns a github commit link based on options.repository: opts.repository + '/commit/' + hash.

• issueLink {function(issueId)} - If repository is provided, this function will be used to link to issues. By default, returns a github issue link based on options.repository: opts.repository + '/issues/' + id.

• log {function()} - What logging function to use. For example, {log: grunt.log.ok}. By default, uses console.log.

• warn {function()} - What warn function to use. For example, {warn: grunt.log.writeln}. By default, uses console.warn.

License

BSD