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

Commits will be made according to the conventional commits specification format.

We will use commitlint to ensure that our commits follow the conventional commits specification and Husky will be used to trigger commit linting.

Conventional Commits

Lets create a test project to demo this. The release-it package needs a know what github repository the project is connected to.

This is because the generated CHANGELOG.md file includes links to the commits. Here’s an example.

## 1.1.0 (2024-06-19)


### Features

* create a commit that demonstrates a commit link ([029acc2](https://github.com/fireflysemantics/ri/commit/029acc2313eb23589a711c3b87d9777d23b20fac))

Therefore 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 ([029acc2](https://github.com/fireflysemantics/ri/commit/029acc2313eb23589a711c3b87d9777d23b20fac))

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.