Development: How to adapt a custom conventional changelog

If you deal with git you will find that predefined commit options are convenient and sometimes necessary in many cases. Automated commit formatting is a good practice and there are tools for that.

While using one of these tools called Commitizen, you’ll be prompted to fill out any required fields at commit time.

No more waiting until later for a git commit hook to run and reject your commit. No more digging through CONTRIBUTING.md to find what the preferred format is. Get instant feedback on your commit message formatting and be prompted for required fields.

You will most certainly need standardized changelog if you:

• work in a large team;
• maintain an open source project;
• run multi component development.

Simple example of conventional changelog in my open source project https://github.com/vladzima/neuronaming-dev

The most famous template for changelog is AngularJS Git Commit Message Conventions. Use can use it from the box with Commitizen, but what if you need a more customized approach tailored specifically for your project? Using cz-customizable plugin you can select the pre-defined scopes for your commit, meaning no more embarrassing spelling mistakes and overall a sustainable readable team-accepted changelog (also good looking).

Let’s dive into it (I will only cover git changelog as I don’t use npm modules).

Installation and configuration.

1. Install Commitizen globally along with cz-customizable plugin:

npm i commitizen -g && npm i cz-customizable -g

2. In your project directory create two files: .czrc and .cz-config.js:

cd [project-directory]
echo '{ "path": "cz-customizable" }' > .czrc && touch .cz-config.js

Note: don’t forget to commit those files to your git.

3. .cz-config.js is the main file where you customize your commit flow. Here is an example config I use in my open source project Neuronaming.

All config options are listed here, but main are scopes and scopeOverrides (along with allowCustomScopes parameter).

• scopes: {Array of Strings}: Specify the scopes for your particular project. Eg.: for some banking system: [“accounts”, “payments”]. For another travelling application: [“bookings”, “search”, “profile”] etc.
• scopeOverrides: {Object where key contains a Array of String}: Use this when you want to override scopes for a specific commit type.
• allowCustomScopes: {boolean, default false}: adds the option custom to scope selection so you can still type a scope if you need.

Other options are basically optional for our cause.

As you could see, in my config I use this particular set of scopes:

scopes: [
 {name: ‘static’},
 {name: ‘server’},
 {name: ‘ml’}
 ],

Customize the scope and overrides as you find most suitable for your project.

Usage.

Using Commitizenscz-cli couldn’t be easier: just replace git commit command with git cz. That’s it, really!

You will be presented with your predefined question set and a preview of your changelog at the end:

In case you’re wondering what’s used in the screenshot: iTerm2 + zsh + powerlevel9k + tmux (unbeatable alliance)

Commitizen is well used with Semantic Release to automatically trigger releases on Github based on commits, but that’s for the next time ;)