Conventional changelog and commitizen

conventional-changelog, https://github.com/conventional-changelog/conventional-changelog, is a tool to generate a changelog, or release notes, from a project's Git metadata, in particular from commit messages. Its companion high-level tool, standard-version (https://github.com/conventional-changelog/standard-version), can be used to automatically bump up app version while generating the changelog. The version bump is done according to commits history and follows semverrules (see Semver).

For these tools to work properly, the developer must follow some conventions when writing commit messages (at least for commits that close some issues or features implementation), as explained in the official documentation at https://conventionalcommits.org/. In particular, the message format is the following:

<type>[optional scope]: <description>

[optional body]

[optional footer]

where:

1. type must be present and can be one of feat, fix or some other custom verbs (more on this later). feat must be used when a commit adds a new feature, fix when it fixes a bug.

2. scope is optional. If present it must be enclosed in parenthesis and describes the changed section of the codebase.

3. After the type(or scopeif present), a colon and a space must be present.

4. description must be present and is a brief description of the changes in the commit.

5. bodyis optional. If present, there must be a blank line before it. This is a longer description of the changes in the commit.

6. footer is optional. If present, there must be a blank line before it. It contains metadata about the commit (e.g. number of task resolved).

7. If a commit introduces a breaking change, it must be indicated at the very beginning of the footeror bodysection of a commit. A breaking change must consist of the uppercase text BREAKING CHANGE, followed by a colon, a space and a mandatory description.

An example of a commit following these rules:

feat(renderer): New renderer with 600% performance increase!

BREAKING CHANGE: Totally new API.

Close #1234.

To use standard-version in your project, just run:

npm i --save-dev standard-version

In the Web development world, there are some other commonly used verbs for covnentional commits, but remembering them all is not that easy. Also, formatting commit messages manually is error prone and very tedious.

committizen(https://github.com/commitizen/cz-cli) to the rescue! This tool is a simple wizard which will guide the developer during the commit message creation, gathering all required information for well-formed conventional commits. Here is how you can configure it for your project:

1. Install dev dependencies:

   npm i --save-dev commitizen cz-conventional-changelog

2. Add a config section to package.json, with the following content:

   "commitizen": {
       "path": "cz-conventional-changelog"
     }
   }

3. Add an npm script to use commitizen from CLI:

   "scripts": {
     ...
     "cz": "git-cz",
     ...
   }

To use the tool:

1. Stage your changes as usual (e.g. command line or Git GUI client).

2. Invoke commitizen wizard. Some ways:

   1. Use the previous npm script via npm run cz, or

   2. Use an extension for your IDE (e.g. https://github.com/KnisterPeter/vscode-commitizen for VSCode).

3. Follow the wizard. That's it!