changelog.md

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.

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

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