Knowledge is only real when shared.
July 26, 2021
Version information in commit messages.
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.
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.
• Used by other developers
• Regularly improved
• Initial development done
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.
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.
fix fixes a bug.
feat introduces a backwards compatible new feature and will force next minor release 1.X.0.
test related to tests.
docs for documentation.
build includes changes to the build.
ci adapts the continuous integration configuration.
refactor for structural changes.
style for formatting.
perf improves execution speed of the software.
revert to revert previous changes.
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.
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.
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.
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.
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.