@release-it/conventional-changelog

What is @release-it/conventional-changelog?

@release-it/conventional-changelog is an npm package that integrates with release-it to automate the generation of changelogs based on conventional commit messages. It helps in maintaining a consistent changelog format and automates the release process.

What are @release-it/conventional-changelog's main functionalities?

Automated Changelog Generation

This feature allows you to automatically generate a changelog based on conventional commit messages. The 'preset' option specifies the convention to follow, such as 'angular'.

{
  "plugins": {
    "@release-it/conventional-changelog": {
      "preset": "angular"
    }
  }
}

Customizable Changelog Presets

You can customize the changelog generation by specifying different presets and output files. The 'infile' option specifies the file where the changelog will be written.

{
  "plugins": {
    "@release-it/conventional-changelog": {
      "preset": "angular",
      "infile": "CHANGELOG.md"
    }
  }
}

Integration with release-it

This feature shows how to integrate @release-it/conventional-changelog with release-it to automate the entire release process, including generating changelogs and committing the release.

{
  "plugins": {
    "@release-it/conventional-changelog": {
      "preset": "angular"
    }
  },
  "git": {
    "commitMessage": "chore(release): ${version}"
  }
}

Other packages similar to @release-it/conventional-changelog

standard-version

standard-version is a similar tool that automates versioning and changelog generation based on conventional commit messages. It is a standalone tool and does not require integration with release-it, making it simpler for projects that do not need the additional features provided by release-it.

semantic-release

semantic-release is a powerful tool that automates the entire package release workflow, including changelog generation, versioning, and publishing. It is more comprehensive than @release-it/conventional-changelog and is suitable for projects that require a fully automated release process.

conventional-changelog-cli

conventional-changelog-cli is a command-line tool for generating changelogs based on conventional commit messages. It is less integrated than @release-it/conventional-changelog but provides a straightforward way to generate changelogs without additional dependencies.

README

Conventional Changelog plugin for release-it

This plugin will provide the recommended bump to release-it, and update the changelog file (e.g. CHANGELOG.md).

npm install --save-dev @release-it/conventional-changelog

Configuration

In the release-it config, for example:

"plugins": {
  "@release-it/conventional-changelog": {
    "preset": "angular",
    "infile": "CHANGELOG.md"
  }
}

Options are passed verbatim to conventional-recommended-bump and conventional-changelog-core.

preset

Use one of:

• angular
• atom
• codemirror
• conventionalcommits
• ember
• eslint
• express
• jquery
• jscs
• jshint

Use an object with name and types to use a custom preset:

"plugins": {
  "@release-it/conventional-changelog": {
    "infile": "CHANGELOG.md",
    "preset": {
      "name": "conventionalcommits",
      "types": [
        {
          "type": "feat",
          "section": "Features"
        },
        {
          "type": "fix",
          "section": "Bug Fixes"
        },
        {}
      ]
    }
  }
}

See the Conventional Changelog Configuration Spec (v2.1.0) for the configuration object to pass as preset.

infile

Default value: undefined

• Set a filename as infile to write the changelog to. If this file does not exist yet, it's created with the full history.
• When infile is not set, the changelog generated by this plugin will still be used as release notes for e.g. GitHub Releases.
• Set infile: false to disable the changelog writing (and only use the recommended bump for the next version).

header

Set the main header for the changelog document:

{
  "plugins": {
    "@release-it/conventional-changelog": {
      "infile": "CHANGELOG.md",
      "header": "# Changelog",
      "preset": {
        "name": "conventionalcommits"
      }
    }
  }
}

ignoreRecommendedBump

Default value: false

Use true to ignore the recommended bump, and use the version provided by release-it (command line argument or prompt).

(Note that the changelog preview shows the recommended bump, as the desired version isn't known yet. The infile will have the correct version.)

strictSemVer

Default value: false

Use true to strictly follow semver, also in consecutive pre-releases. This means that from a pre-release, a recommended bump will result in a next pre-release for the next version.

For example, from 1.0.0-alpha.0 a recommended bump of minor will result in a preminor bump to 1.1.0-alpha.0 (whereas the default behavior without this flag results in a prerelease bump to 1.0.0-alpha.1).

context

Default value: undefined

This option will be passed as the second argument (context) to conventional-changelog-core, for example:

"plugins": {
  "@release-it/conventional-changelog": {
    "context": {
      "linkCompare": false
    }
  }
}

gitRawCommitsOpts

Default value: undefined

Options for git-raw-commits. For example, you can use the following option to include merge commits into changelog:

{
  "plugins": {
    "@release-it/conventional-changelog": {
      "gitRawCommitsOpts": {
        "merges": null
      }
    }
  }
}

parserOpts

Default value: undefined

Options for conventional-commits-parser. For example, you can use the following option to set the merge pattern during parsing the commit message:

{
  "plugins": {
    "@release-it/conventional-changelog": {
      "parserOpts": {
        "mergePattern": "^Merge pull request #(\\d+) from (.*)$"
      }
    }
  }
}

writerOpts

Default value: undefined

Options for conventional-changelog-writer. For example, you can use the following option to group the commits by 'scope' instead of 'type' by default.

{
  "plugins": {
    "@release-it/conventional-changelog": {
      "writerOpts": {
        "groupBy:" "scope"
      }
    }
  }
}

If you want to customize the templates used to write the changelog, you can do it like in a .release-it.js file like so:

const fs = require('fs');

const commitTemplate = fs.readFileSync('commit.hbs').toString();

module.exports = {
  plugins: {
    '@release-it/conventional-changelog': {
      writerOpts: {
        commitPartial: commitTemplate
      }
    }
  }
};

Command-line

Options for this plugin can be set from the command line. Some examples:

release-it --plugins.@release-it/conventional-changelog.infile=history.md
release-it --no-plugins.@release-it/conventional-changelog.infile

• Keys are separated by dots.
• Values can be negated by prefixing the key with no-.
• Arguments may need to be single-quoted (') such as --'deep.key=value' or '--deep.key=value'

Depending on your shell or OS this may differ.

GitHub Actions

When using this plugin in a GitHub Action, make sure to set fetch-depth: 0 so the history is available to determine the correct recommended bump and changelog.

Also see https://github.com/release-it/release-it/blob/master/docs/ci.md#github-actions