<onWebFocus />

Knowledge is only real when shared.


July 26, 2021

Version information in commit messages.

Commit Lint

Please pick at least a type and enter a summary.

Standardized commit messages are a way to automatically version releases and generate changelogs. You describe every change in detail when committing. That way you don't have to go back once enough changes have accumulated and it's time for a release. This greatly reduces the risk of forgetting about features or breaking changes when you do the release.

When should I use it?

Use this commit conventin when creating software that's used as code instead of as a product. So, it should be used for a plugin you've created for other developers at your company and is used on multiple websites. However it makes no sense to use it for a website or mobile app. Also the software should constantly be improved and not just be a single release and maybe a rewrite every now and then.

How does it work?

Based on a convention to describe the commit the software can later automatically figure out the next version. Check out the previous post Version to learn more about how to version software.

What does it look like?

feat(markup): adapt default space after header component

Switch default margin after header from 10px to 20px to attain compliance with the UI standard spacing convention.

BREAKING CHANGE: default space after header doubled, set `space=10` to keep current layout.

Above you see an example of such a commit message. The first line is called the header while other two are called the body and the footer both being optional.

The tool at the top of the article assists you in generating such a message. The different parts there are now described in detail.


The type describes how the change interacts with the external users of the software. There are two main types fix and feat which relate to a patch release or a minor release for the latter. Arbitrary other types can be used as well but carry no structural meaning describing the change. These other types are used for things which have no direct impact on the user. These mostly include quality, performance or usability improvements. These types can also be used to distinguish commits not related to the software like documentation or demo improvements. Apart from fix and feat the following list includes our recommended selection.

A BREAKING CHANGE note can be added to the footer of any type. This indicates a non backwards compatible change in the interface of the software. A breaking change in one of the commits of the next release will force the next major version X.0.0 for the release.

The type chore is used for automatically generated release commits. When used otherwise it often includes changes that could be automated or are missing an approprite type.


Adding a scope is optional and should be used to show the context of the change. This gives other people looking at the commits a quick overview of what might have changed and lets them ignore irrelevant commits quickly.


Succinctly describes the change made.


If necessary this should be a more detailed description of the change and most importantly explain why the change is made.


Contains information about breaking changes and if avilable references Issues or Tickets. A reference to an issue or several issues done with this commit could look like Fixes #123 or Resolves #45, #67. The hash in front is important as issues referenced this way will automatically be closed once the commit lands in the repository.

Release tools

Commits annotated in this way are called Conventional Commits. The good thing is that you can now automatically generate the proper next release version and a changelog. The most popular tool to do this is semantic-release followed by standard-version. Semantic release fully automates creating a release and is thought for automated releases inside Continuous Integration.

npx standard-version

Running this command will bump the version to the next appropriate version according to the commits since the previous release. It will create a commit with the changed version in your package.json and a tag named after the version. The tag is used to identify possible releases for GitHub releases. Regular commits without annotations will be ignored and won't cause any issues. Releasing for this first time add the --first-release flag and the version won't be changed while creating a CHANGELOG.md file.

Release npm Action

Update A release flag can now be set in the above tool that will tell the release-npm-action to trigger a release if any relevant changes are found. This action is described in more detail in the GitHub npm Release Action post in this blog.


If your committing from a graphical tool like source tree it's best to use the tool at the start of this post as there are no plugins to compose conventional commit messages inside these tools yet. If you use the CLI however you can use commitizen to prompt for the necessary details.

Other ways

You'll find a lot of popular packages that don't use this approach. The reason for this is that these projects actively plan their releases to make sure breaking changes only occur every now and then. The planned major releases have some planned changes that are definitively required. While contributors work on other issues it's decided when merging the pull request for a certain feature into which release the change goes or when it can be merged.