Semantic commits in the use of Git and other VCS (code versioning systems) are the best way to document implementation execution, as they give context to change management.
Write unclear commit messages, such as
task done or
bug fixed they do not help in the maintenance of code and the evolutionary history of the system.
Review the commit message history below:
commits e71fcf2022b6135e18777bdc58c2ac3180202ec7 Author: mazerdev Date: Tue Apr 24 01:25:48 +1000 2021 Extract commit payment information d1952883b05b685f2d22e4c41b4fbc4362fd6bd0 Author: mazerdev Date: Mon Apr 23 22:16:50 +1000 2021 [WIP] integration commit 74b8920d96e3e09d5cd958ffa369a0e3c86a6851 Author: mazerdev Date : Mon Apr 23 21:09:11 2021 +1000 Generate payment link commit b02255b25eed57c7595504c66233d5ee3024190c Author: mazerdev Date: Mon Apr 23 18:32:40 2021 +1000 [WIP] Search widgets
The thought of those who write the commits like this would be: “I will never worry about using the commit body”.
When you are working at a company that when creating a PR, doing code review is not common, no one will bother asking you to write a good commit message.
However, that changes when you start working with teams with a good engineering culture, where writing an explicit and semantic commit message defines the acceptance and quality of your deliverables.
Where to start?
Most programming languages have well-established conventions about what constitutes their idiomatic style, namely, naming, formatting, and so on.
There are variations on these conventions, but most developers would agree that picking one and sticking to it is far better than the chaos that arises when everyone makes their own choices in shared code.
It's important then to understand that a team's approach to their commit log shouldn't be any different.
To create a useful revision history, teams must first agree on a commit message convention that establishes at least three things:
- Style: Markup syntax, margin break, grammar, capitalization, punctuation. Remove those things, eliminate the guesswork, and make everything as simple as possible. The end result will be a remarkably consistent record that is not only a pleasure to read, but is actually read regularly.
- Contents: What kind of information should the commit message body contain (if any)? What shouldn't it contain?
- Metadata: Like issue and task tracking IDs, Pull and Merge Requests ids, etc. should they be referenced?
Fortunately, as with programming languages, there are well-established conventions on how a Git commit message should be written to be idiomatic.
So there's nothing you and your team need to reinvent. Just follow the seven rules below and you'll be on your way to committing 😀 like a pro.
The seven rules for a semantic Git commit message
- Separate the subject from the body with a blank line
- Limit the subject line to 50 characters
- Capitalize the subject line
- Don't end the subject line with a period
- Use imperative humor in the subject line
- Wrap the body in 72 characters
- Use the body to explain the what and why vs. how
Conventional Commits for semantic commits
The specification defined by Conventional Commits is to provide a simple convention to use in commit messages.
It defines a set of rules for creating an explicit commit history, which facilitates the creation of automated tools based on the specification.
This convention aligns with the Without seeing, describing the features, fixes, and changes that break compatibility, all in the commit messages.
The commit message should be structured as follows:
[optional scope]: [optional body] [optional footer(s)]
Let's understand what each block of information means and how it should be filled.
The commit message contains the following structural elements, to communicate the intent to the user of your library:
- fix: a commit of type
fixsolves a problem in your codebase (this correlates with
PATCHof semantic versioning).
- feat: a commit of type
featadds a new feature to your codebase (this correlates with
MINORof semantic versioning).
- BREAKING CHANGE: a commit that contains in the optional footer the text
BREAKING CHANGE:, or contains the symbol
!after type/scope, introduces a modification that breaks API compatibility (this correlates with
MAJORof semantic versioning). A BREAKING CHANGE can be part of commits of any type.
- Others types additional are allowed in addition to
feat:, for example @commitlint/config-conventional (based on Angular Convention) is recommended
test:, among others.
- Others baseboards different from
BREAKING CHANGE:can be provided and follow the convention to simulate the git trailer format.
Note that these additional types are not required by the Conventional Commits specification and have no implicit effect on semantic versioning (unless they include a
BREAKING CHANGE). A scope can be given to the commit type, to provide additional contextual information and is contained in parentheses, for example
feat(parser): adds ability to parse arrays.
- Conventional Commits
- Meaningful commit messages with conventional commits
- Karma Commit Style
- Understanding Semantic Commit Messages with Angular
- Gist Semantic Commit Messages