How to Automatically Generate Changelog for your node.js projects (step by step)

When are working on a software project a common task during the process will generate a changelog when a new software version is going to be released. It will contain all the changes, bug fixes, and new features made since the last release.

Generally, changelog creation is a manual task that takes much time and includes errors during the process from the people that are involved in the software process. For that reason during this post will be described some helpful tools for that specific process to save a lot of time.

Semantic Versioning

Semantic versioning is a versioning system that has been on the rise over the last few years. The release has always been a problem for software developers, release managers, and others involved in the development process. Thus a universal way of versioning the software development projects is the best way to track what is going on with the software as integration new plugins, addons, libraries, and the new features that will be created almost every day.

Given a version number MAJOR.MINOR.PATCH, increment the:

• MAJOR version: When you make incompatible API changes
• MINOR version: When you add functionality in a backward-compatible manner
• PATCH version: When you make backward-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

First steps

First of all, we need to use and standardize in our project the commits, For that can be used this previous post Integrate Commitizen with your node.js project or integrate a standardization based on Conventional Commits Specification

The Conventional Commits specification proposes introducing a standardized lightweight convention on top of commit messages. This convention dovetails with SemVer, asking software developers to describe in commit messages, features, fixes, and breaking changes that they make.

The commit format

<type>[optional scope]: <description>

[optional body]

[optional footer]

The main reason to do that is that the commits will be used to generate the automatic changelog file.

Setup

First of all, we need to install a new dependency

npm i --save-dev standard-version

After that, you can add some new npm run scripts to the package.json file

{
  ...
  "scripts": {
    "release": "standard-version",
    "release:minor": "standard-version --release-as minor",
    "release:patch": "standard-version --release-as patch",
    "release:major": "standard-version --release-as major"
  }
}

The changelog generation can be configured via a .versionrc.json file or placing a standard-version config in package.json.

In this case, we will create the .versionrc.json file based on the Conventional Changelog Configuration Spec

{
    "types": [
      {"type": "feat", "section": "Features"},
      {"type": "fix", "section": "Bug Fixes"},
      {"type": "chore", "hidden": true},
      {"type": "docs", "hidden": true},
      {"type": "style", "hidden": true},
      {"type": "refactor", "hidden": true},
      {"type": "perf", "hidden": true},
      {"type": "test", "hidden": true}
    ],
    "commitUrlFormat": "https://github.com/USERNAME/REPOSITORY_NAME/commits{{hash}}",
    "compareUrlFormat": "https://github.com/USERNAME/REPOSITORY_NAME/compare/{{previousTag}}...{{currentTag}}"
  }

First Release (Optional)

The first release can be created executing the next command in the terminal

npm run release -- --first-release

Will generate the next output

skip version bump on first release
✔ created CHANGELOG.md
✔ outputting changes to CHANGELOG.md
✔ committing CHANGELOG.md
✔ tagging release v1.0.0
ℹ Run `git push --follow-tags origin main` to publish

The command generates also the tags related to the release so need to be pushed to the repository

References

• Conventional Commits
• Integrate Commitizen with your node.js project
• Semantic Versioning
• Standard version

Comments

[Alex Martins]

I am getting this error:

npm ERR! functions@ release: standard-version "--first-release"

[Brayan Arrieta]

With which command or step you received that error, I will be checking tomorrow so you feedback is really appreciated @martinslae

[crisarji]

Useful indeed!, I work with this approach since several months ago and it is a time saver, doing this manually among dozens of devs would be a total mess.

[Benjamin Grand]

Thanks for informations 🙂

[Baruch Odem]

After reading this, if you want to customize your commit conventions and your flow, you may read this:
dev.to/baruchiro/how-to-setup-auto...