Automating changelogs in your NodeJS project

Translated from my article in Brazilian Portuguese version.

Thanks my friend Guilherme Virtuoso for helping to translate the article.

- Portuguese-BR version

Writing the application changelog manually is always painful. You need to remember all changes after finishing the task, keeping everything organized according to project or company standards. You can easily miss something here creating some kind of inconsistent data.

A few months ago I started to work in a lot of projects in parallel and I had to figure out a way to automate and standardize this process about documenting the epics of my application development flow and it was when I found the auto-changelog dependency that has fitted my needs.

That configuration is recommended for new projects or for projects that follow a commit message pattern since the beginning. This kind of validation could be done using git hooks or even manually by developers.

Repository with a starter kit including all configurations made reading this article: https://github.com/tiagoboeing/auto-changelog-starter-kit

Guess what will be the output?

Changelog sample — auth application — unreleased version — ClickUp integration.

This is how the commit messages look like: (I took the first commit to explain)

On this article the commit versions are using the SEMVER standard:
Eg: 1.0.0; 1.1.0; 2.0.0; 2.0.1 …….… 33.22.1

Let’s get started!

Install the auto-changelog dependency in your project.

npm install auto-changelog --save-dev
# or
yarn add auto-changelog --dev

For test purposes, you can install globally:

npm install -g auto-changelog

If you don’t have installed globally you have to configure your package.json file to run the auto-changelog script:

scripts: {
   "changelog": "auto-changelog --template changelog-template.hbs -p -u --commit-limit false",
   "changelog-debug": "auto-changelog --template changelog-template.hbs -p --template json --output changelog-data.json"
}
...

On the example above, the only required script is the changelog. The changelog-debug is optional although is extremely interesting if you want to check how your changelog is being generated.

Creating the changelog:

auto-changelog --template changelog-template.hbs -p -u --commit-limit false

• auto-changelog — node module command
• --template changelog-template.hbs — parameter to setup a pattern file for your changelog messages
• -p — use the SEMVER version from package.json as latest release
• -u — include unreleased changes to the changelog
• --commit-limit false — remove the limit about number of commits per release on the changelog (default: 3)

The default changelog file name is “CHANGELOG.md”

You can customize the file name with -o or --output (Eg: -o HISTORY.md)

3rd party integrations (ClickUp, Jira, etc.) and restricting branches

This step is very important for auto-changelog dependency works properly.
If you don’t integrate with other services like ClickUp or Jira you can remove or just initialize with an empty object or empty string ( {} or "") the attributes below:

• replaceText
• issueUrl

In your package.json create a new property and including:

"auto-changelog": {
   "commitLimit": false,
   "unreleased": true,
   "issueUrl": "https://app.clickup.com/t/{id}",
   "replaceText": {
      "[Ff]eature:": "",
      "[Ff]ix:": "",
      "[Bb]reak:": "",
      "^ #(.{6})\\s": "[$1](https://app.clickup.com/t/$1) - "
   },
   "includeBranch": [
      "develop",
      "master"
   ]
}

• issueUrl — setup the link pattern for the task
• replaceText — remove the words used in our commit message (In our case: fix, feature ou break)
• “^ #(.{ … — it tooks the task number and create a markdown link. Eg: #1b1d0g turns into * [1b1c76](https://app.clickup.com/t/1b1c76)
• includeBranch — restrict from which branches the messages should come. (Eg. develop and master) (Interesting when you have standard messages for yours MR/PR avoiding also that a lot of unwanted messages be added)

You can use the properties commitLimit and unreleased as a fallback even overwritten by the command line. It’s optional.

Do you prefer Jira?

No problem, use the example below:

"auto-changelog": {
    "commitLimit": false,
    "unreleased": true,
    "issueUrl": "http://jira.user.com.br/browse/{id}",
    "replaceText": {
      "[Ff]eature:": "",
      "[Ff]ix:": "",
      "[Bb]reak:": "",
      "([A-Z]+-\\d+)": "[$1](http://jira.user.com.br/browse/$1) - "
    },
    "includeBranch": [
      "develop",
      "master"
    ]
}

Setup changelog pattern

On the root folder, together with your package.json file, create a file with the same value setup on the property --template. In our example, the name is changelog-template.hbs

Paste this content to the file:

Understanding the template

You have to use the auto-changelog variables with an interpolation like: {{var}}

• {{#each releases}} : iterates over each release, in our case we are including which was not generated yet.
• # {{title}} : we create a markdown header level 1 that will contain the version name (Like 1.0.0). Just below we add the version date using the ISO 2020–01–03 standard.
• We create three sections on the changelog (new features, fixes (bugfix, hotfix, etc.), and compatibility breaks).
• Create three sections in changelog, one for new features, fixes (bugfix, hotfix, etc.) and just breaking compatibility.
• {{#commit-list}} : Iterates over the commit list trying to match the message regex pattern. It will also exclude the commits that match with the “exclude” option.

How to use?

If you didn’t change anything in order to customize by your own way, we will have three possible sections:

• feature:
• fix:
• break:

You should add in your commit message one of these keywords. Check below an example simulating a commit of our task related to the ClickUp integration:

feature: #1b1d0g Adiciona nova dependência

Don’t have a task on ClickUp, Jira, etc.?

feature: Adiciona nova dependência

Building your changelog

We are done! Now is just a matter of run the command:

npm run changelog
# or
yarn changelog

If you want to check in a json file what will be generated, run npm run changelog-debug and in the root folder you will find a file called “changelog-data.json”. That was the reason why we have created a tag called changelog-debug on the script section in your package.json

The final output will be a file called CHANGELOG.md. Be careful here, if you already have a file with that name the file will be overwritten.

It’s a good idea implement this step in your CI pipeline ;-)

Extra

• auto-changelog on NPMJS: https://www.npmjs.com/package/auto-changelog
• Github Official repo: https://github.com/CookPete/auto-changelog