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"
        },
        {
          "type": "docs",
          "section": "Documentation",
          "effect": "changelog"
        },
        {
          "type": "chore",
          "effect": "hidden"
        }
      ]
    }
  }
}

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

With the conventionalcommits preset, types[].effect controls changelog visibility and recommended bumps for non-breaking commits:

• bump includes the commit in the changelog and bump recommendation. This is the default.
• changelog includes the commit in the changelog without triggering a bump.
• hidden excludes the commit from both.

Breaking changes still trigger a major bump regardless of their type effect. See the Conventional Commits preset options for the full configuration contract.

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.

Promoting a pre-release

The release-it git.tagExclude option only affects release-it's version lookup. The recommended bump and changelog writer have their own tag policies. Configure all three when a stable release should include every commit since the previous stable version:

{
  "git": {
    "tagExclude": "*.*.*-*"
  },
  "plugins": {
    "@release-it/conventional-changelog": {
      "tagOpts": {
        "skipUnstable": true
      },
      "writerOpts": {
        "generateOn": null
      }
    }
  }
}

tagOpts.skipUnstable calculates the recommendation from the previous stable tag. writerOpts.generateOn: null keeps intermediate prerelease tags from splitting those commits into separate changelog blocks.

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

Customize the render functions in a .release-it.js file:

module.exports = {
  plugins: {
    '@release-it/conventional-changelog': {
      writerOpts: {
        commitPartial: (_context, commit) => `- ${commit.header}`
      }
    }
  }
};

template, headerPartial, preamblePartial, commitPartial, and footerPartial accept render functions. Handlebars template strings and partial files are no longer supported.

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

Since conventional-changelog-writer@9, 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 v7. This error means your dependency tree resolved an older incompatible version. Usually another dependency (e.g. @commitlint/cli) pulls in an older version, and legacy-peer-deps=true (or the yarn/pnpm equivalent) lets it win over git-client's ^7 peer requirement.

Check which version is resolved:

npm ls conventional-commits-parser

Then fix it on your side with one of:

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

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

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