Automate JavaScript project versioning with commitizen and standard-version

Published in

Tunaiku Tech

5 min readNov 1, 2019

It is such a hassle to manually update versions, changelogs, and create git tags. Ever wonder if there is a better way of doing this? Fear not, standard-version will do everything that is said in a single command line!! To implement the auto versioning, there are several configurations that need to be done though.

Install commitizen

Before we use standard-version, it is required to standardise the commit messages using the Conventional Commit Specifications. This is because standard-version will bump version (major, minor, or patch) based on the commit types (feature bumps minor, bug fix bumps patch, BREAKING CHANGES bumps major, and so on). However, rest assured, a package called commitizen will help us generate commit messages which adhere to Conventional Commit Specifications. To install commitizen, do the following:

Install commitizen within your JavaScript project:

npm install -D commitizen

2. Setup adapter for changelog:

commitizen init cz-conventional-changelog --save-dev --save-exact

3. In package.json, add the following scripts:

"scripts": {  "commit" : "git-cz"}

To execute commitizen, we first do git add . files and then run npm run commit which will ask what kind of commits we are committing (feat, chore, fix, etc.) in the CLI, like the following:

CLI after running the command git-cz (1)

After we select the option, it will ask the details of that commit:

CLI after running the command git-cz (2)

At this point, our changes have been committed and we are ready to configure standard-version.

Install standard-version

After we have configured standardised commits using commitizen and git-cz, we can now setup automate versioning, update CHANGELOG.md, and git tag creations using standard-version.

1. Install standard-version through npm:

npm install -D standard-version

2. Setup a customised script command within package.json:

"scripts": {  "commit" : "git-cz",  "release": "standard-version"}

To use standard-version properly, we first git add . files, commit using npm run commit, and finally run the command npm run release.

CHANGELOG.md configuration specs

By default, standard-version only records commit type feat and fix to CHANGELOG.md. To enable other commit types, do the following:

Create a new file in the root folder called .versionrc and paste the following configuration specs:

Example standard-version configuration specs

"type" → refers to the commit types
"section" → is what the corresponding commit types heading would be in the CHANGELOG.md
"hidden" → determines whether a commit type should appear or not in the CHANGELOG.md

Development Workflow

Now that everything has been configured, let’s take a look at the example of real development workflow so that it is clear when to execute commitizen and standard-version.

1. [feature-branch] Stage modified files using:

git add .

2. [feature-branch] Commit the files using git-cz package:

npm run commit

Choose the type of the commits (feat, refactor, fix, etc.).
Provides a short description of the commits.
(Optional) Provides a longer description.
Determine whether the commit is a BREAKING CHANGES or not (by answering ‘y’ and fill up BREAKING CHANGES descriptions in the CLI).
(Optional) Mentions the JIRA issue in (by answering ‘y’ and fill up the issue descriptions in the CLI).

3. [feature-branch] Now that all files have been committed, they are ready to be pushed to the remote:

git push origin <feature-branch>

4. [Bitbucket]Create a Pull Request to master branch.

5. [master] After it is merged, the following steps are done within the master branch:

Run the command npm run release (which will bump versions based on commit types, add commit descriptions to CHANGELOG.md, and create git tags according to the current version).
Push changes and git tags to master branch using :

git push --follow-tags origin master

6. Relax and enjoy 🍕

Conclusion

It is considered a good practice to document (bump versions based on semver, update changelogs, and possibly create git tag) each time a feature is released to production. It is great because we can easily keep track any changes that have been made chronologically. Fortunately, this can now be done automatically using tools, such as commitizen (standardising commit messages) and standard-version (automatically bump versions, update changelogs, and git tag creations based on commit types).

Facts and Common Pitfalls🤔

BREAKING CHANGES commit (using git-cz) WILL NOT bump major version if there is NO major version just yet!!! Let’s say the current version is 0.1.2, if we run npm run release it will only bump either minor or patch version (see: https://github.com/conventional-changelog/standard-version/issues/429).
To bump major version properly (via standard-version), we first need to explicitly release a major version using the command:

standard-version -- --release-as major

Note: the double hyphen -- after standard-version is required and there is a space in between --release-as and major .

Then, if we release another BREAKING CHANGES commit type, it will now bump the major version properly 👍🎉.
By default, standard-version only records commit type feat and fix to the CHANGELOG.md. To record other commit types, create a config file called .versionrc in the root project folder.
Running the command npm run release when there are multiple commit types (e.g. feat - bumps minor version, and then fix - bump patch version), upon merging the commits, the version is bumped according to the following precedence: