How to Automatically Generate Changelog for your node.js projects (step by step)
Tags: node, github, programming, changelog
Published: 2021-04-02 18:45:47

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](https://semver.org/) 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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/wjlxt40w9kzayorc9msn.png)


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](https://dev.to/brayanarrieta/integrate-commitizen-with-your-node-js-project-53kf) or integrate a standardization based on [Conventional Commits Specification](https://www.conventionalcommits.org/en/v1.0.0/)

> 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

```shell
npm i --save-dev standard-version
```

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

```json
{
  ...
  "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](https://github.com/conventional-changelog/conventional-changelog-config-spec/blob/master/versions/2.1.0/README.md)


```json
{
    "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
```shell
npm run release -- --first-release
```
Will generate the next output
```shell
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](https://www.conventionalcommits.org/en/v1.0.0/)
- [Integrate Commitizen with your node.js project](https://dev.to/brayanarrieta/integrate-commitizen-with-your-node-js-project-53kf)
- [Semantic Versioning](https://semver.org/)
- [Standard version](https://www.npmjs.com/package/standard-version)