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": {
      "name": "angular"
    },
    "infile": "CHANGELOG.md"
  }
}

The plugin is a wrapper around conventional-changelog packages conventional-recommended-bump, conventional-changelog and more.

Contents

• preset
• Bump
  • commitsOpts
  • tagOpts
  • whatBump
  • ignoreRecommendedBump
  • strictSemVer
• Changelog
  • infile
  • header
  • context
  • gitRawCommitsOpts
  • parserOpts
  • writerOpts

preset

For preset.name, 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"
        },
        {}
      ]
    }
  }
}

This is passed as the first argument to bumper.loadPreset (in both bumper and changelog writer).

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

Bump

tagOpts

• This option will be passed as the first argument to bumper.tag
• Type definition for tagOpts → look for GetSemverTagsParams

commitsOpts

• This option will be passed as the first argument to bumper.commits
• Type definition for commitsOpts → look for GetCommitsParams

whatBump

• This option will be passed as the first argument to bumper.bump
• Type definition for whatBump → look for Preset['whatBump']
• Use false to skip releasing a new version:

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

• Use a function to manually provide a bump:

module.exports = {
  plugins: {
    '@release-it/conventional-changelog': {
      whatBump: function () {
        return { releaseType: '10.0.1' };
      }
    }
  }
};

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 in the release-it process. 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.

The default behavior results in a prerelease bump to 1.0.0-alpha.1.

Changelog

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

Default value: "# Changelog"

Set the main header for the changelog document:

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

context

Default value: undefined

This option will be passed as the second argument (context) to conventional-changelog, 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
• This option will also be passed as the second argument to bumper.parserOptions
• Type definition for parserOpts → look for ParserOptions

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
• Type definition for writerOpts → look for Options

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
      }
    }
  }
};

A custom writerOpts.transform replaces the preset's own transform (the one that maps commit types to sections via preset.types and strips hidden types). Override it and you lose that behavior. Raw types appear and hidden types reappear. To filter or reshape the output while keeping the preset behavior, use finalizeContext instead.

Since conventional-changelog-writer@10, the commit passed to transform is read-only. Return an extended object instead of mutating it:

// Wrong: no-op or throws, the commit is read-only
transform: commit => { commit.scope = '...'; return commit; }

// Right: return an extended copy
transform: commit => ({ ...commit, scope: '...' })

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/main/docs/ci.md#github-actions

Troubleshooting

parseCommits is not a function

@conventional-changelog/git-client dynamically imports conventional-commits-parser and needs v6+ (only v6 exports parseCommits). This error means your dependency tree resolved an older conventional-commits-parser@5 for it. Usually another dependency (e.g. @commitlint/cli) pulls in v5, and legacy-peer-deps=true (or the yarn/pnpm equivalent) lets it win over git-client's ^6 peer requirement.

Check which version is resolved:

npm ls conventional-commits-parser

Then fix it on your side with one of:

• Force a single v6 via overrides (npm) / resolutions (yarn) / pnpm.overrides:

  {
    "overrides": {
      "conventional-commits-parser": "^6"
    }
  }

• Remove legacy-peer-deps=true from your .npmrc so the ^6 peer requirement is honored.
• Update the conflicting dependency (e.g. @commitlint/*) to a version that uses v6.