Changelog

By default, release-it generates a changelog, to show and help select a version for the new release. It contains all commits since the latest tag.

The default command is based on git log .... This setting (git.changelog) can be overridden. Make sure any of these commands output the changelog to stdout.

Hide release preview output

For projects with very long changelogs or noisy diffs, you can suppress the preview blocks printed during the release flow (changelog, changeset, and release notes) to avoid flooding the console. A single notice is printed so it is clear that previews were hidden. This does not affect the --changelog mode, which prints the changelog and exits.

{
  "quiet": true
}

Or via the CLI:

release-it --quiet

• GitHub and GitLab Releases
• auto-changelog
• Conventional Changelog
• Keep A Changelog
• git-cliff

Some projects keep their changelog in e.g. CHANGELOG.md or history.md. To auto-update this file and include this in the release commit, the recommended configuration is to do this in the after:bump hook (see example below).

GitHub and GitLab Releases

The output of git.changelog also serves as the release notes for the GitHub or GitLab release. To customize the release notes for the GitHub or GitLab release, use github.releaseNotes or gitlab.releaseNotes. Make sure any of these commands output the changelog to stdout.

Auto-changelog

For a more rich changelog (e.g. with headers, sections), a (Handlebars) template can be used to generate the changelog. For this, auto-changelog is a great companion to release-it:

{
  "git": {
    "changelog": "npx auto-changelog --stdout --commit-limit false -u --template https://raw.githubusercontent.com/release-it/release-it/main/templates/changelog-compact.hbs"
  },
  "hooks": {
    "after:bump": "npx auto-changelog -p"
  }
}

With this git.changelog, the changelog preview is based on the changelog-compact.hbs template file.

Additionally, hooks.after:bump will update the CHANGELOG.md with each release to get included with the release commit. This can be omitted if the project does not keep a CHANGELOG.md or similar.

See the auto-changelog recipe for an example setup and template.

Conventional Changelog

If your project follows conventions, such as the Angular commit guidelines, the @release-it/conventional-changelog plugin is useful.

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

Use this plugin to get the recommended bump based on the commit messages.

Additionally, it can generate a conventional changelog, and optionally update the CHANGELOG.md file in the process.

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

Keep A Changelog

If your project follows the Keep a Changelog conventions, the @release-it/keep-a-changelog plugin is useful. It updates the CHANGELOG.md file according to the convention of using human-readable items and an "Unreleased" section.

The GitHub releases section could then be used for either a copy of this changelog, or for a log of commits (github.releaseNotes: "git log ...").

npm install @release-it/keep-a-changelog --save-dev

This plugin updates CHANGELOG.md file according to

{
  "plugins": {
    "@release-it/keep-a-changelog": {
      "filename": "CHANGELOG.md"
    }
  }
}

Git-cliff

Git-cliff is a customizable changelog generator that follows Conventional Commit specifications. Similar to auto-changelog, it can be used as a companion to release-it.

See the git-cliff recipe for an example setup.