Generate the Changelog with Release-It and Conventional Commits

Scenario

When we run npm run release we want release-it to generate our changelog CHANGELOG.md.

Approach

We will use commitlint to to make sure that our commits are made using the conventional commits specification and Husky to trigger commit linting. This is what enables us to generate the changelog using the conventional commits.

Conventional Commits

Lets create a test project to demo this. The release-it package needs an actual Github connected repo to generate a proper changelog, so we’ll be creating a Github repo using the Github CLI. If you don’t have it setup there’s instructions here.

Create a Github Repo From the Command Line

Run these commands.

mkdir ri && cd ri && git init -b main
gh repo create ri --public
git remote add origin git@github.com:fireflysemantics/ri.git

Add node_modules to .gitignore .

echo "node_modules" > .gitignore

Install the release-it and the @release-it/conventional-change plugin .

npm i -D release-it @release-it/conventional-changelog

Initialize release-it (Select package.json for the configuration).

npm init release-it

Complete the release it configuration in package.json.

"release-it": {
    "git": {
      "commitMessage": "chore: release ${version}"
    },
    "github": {
      "release": true
    },
    "npm": {
      "publish": false
    },
    "plugins": {
      "@release-it/conventional-changelog": {
        "infile": "CHANGELOG.md",
        "preset": {
          "name": "conventionalcommits",
          "type": [
            { "type": "feat", "section": "Features"},
            { "type": "fix", "section": "Bug Fixes"}
          ]
        }
      }
    } 
  }

Do an intitial commit and test release-it. Note that we must git push — set-upstream origin main otherwise we will an error message saying ERROR No upstream configured for current branch.

git add . && git commit -m "feat: add release it changelog generation"
git push --set-upstream origin main  
npx release-it

We can see that it generated the following CHANGELOG.md file.

## 1.1.0 (2024-03-20)


### Features

* add release it changelog generation 80e627c

Install the commitlint dependencies.

npm i -D @commitlint/cli @commitlint/config-conventional

Extend the commitlint conventional configuration.

echo "module.exports = { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js

Install and initialize Husky.

npm i -D husky && npx husky init

Remove npm test from the .husky/pre-commit file (Otherwise it will can an error since we don’t have a script for this). We can just recreate the file to remove it.

 echo "" > .husky/pre-commit

In order to trigger commitlint when commits are made, create the commit-msg file in the .husky project folder.

echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg

And make commit-msg executable.

chmod a+x .husky/commit-msg

Now test commit linting by using a non conforming header.

git add . && git commit -m "Non conforming"

We should get a linting message like this:

⧗   input: Non conforming
✖   subject may not be empty [subject-empty]
✖   type may not be empty [type-empty]

✖   found 2 problems, 0 warnings
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

Try it again with a conforming commit message.

git add . && git commit -m "feat: add commit linting"

And rerun npx release-it.