DEV Community

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

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

brayanarrieta profile image Brayan Arrieta Updated on ・3 min read

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.

Semantic versioning Image

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]
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"
  }
}
Enter fullscreen mode Exit fullscreen mode

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

Enter fullscreen mode Exit fullscreen mode

First Release (Optional)

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

npm run release -- --first-release
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

References

Discussion (2)

pic
Editor guide
Collapse
crisarji profile image
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.

Collapse
bgrand_ch profile image
Benjamin Grand

Thanks for informations 🙂