Commit Messages are a clue to understanding the meaning of the code. It also gives insights related to the flow and direction of the project development and the history of your components and modules.
We all aware of how difficult it can be to name things, and writing descriptive yet succinct commits can be even more difficult, so adopting a convention that simplifies the process of writing a commit would be great
Given this, it makes sense that the Message should be concise and clearly explain the meaning of the code in order to facilitate the comprehension of the Commit content
🐱💻 Good Commit Message
Before we see how to write a good Commit Message, we need to define a good Commit Message, which simply could be defined as follows:
• Should be more descriptive
• Should be easy to understand them
• Should help us to know what is the scope of the changes
• Should help us to generate CHANGELOGs describes the scope of changes
💩 Bad commit message
Bad commit messages can be OK at the beginning but, sooner or later, you will have problems.
Let's take an example:
$ git log --oneline ./src/components/button/
daccff1f test should pass
3fff19f6 test should pass
5b998d9a add a disabled property for the button
06faab4d fix lint
186cce90 refactor button
4b99d91a fix spinner component
5b998d9a fix css
263288a5 test should pass
c3fb85af Create Button component
There's might be nothing wrong with you with this log. Let me show you the potential issues with this log:
• Hard to understand component’s history
• We might repeat errors already fixed
• There are unnecessary commits that pollute logs and make history hard to read
• Functionalities like git blame become irrelevant
• It seems that a feature was added by a few commits. Which commit should
I include if I want to revert this operation?
✨ Conventional Commit
Conventional Commits is a specification for adding human and machine-readable meaning to commit messages dovetailing with SemVer inspired by the Angular Commit Guidelines .
Conventional Commits specification provides an easy set of rules for creating an explicit commit history by describing the features, fixes, and breaking changes made in commit messages.
🏗 Conventional Commit Message Format
Conventional commit message consists of 5 parts and should be structured as follows:
<type>[optional scope]: <description>
[optional body]
[optional footer]
⛔ Important note
Any line of the commit message shouldn't be longer than 72 characters! This allows the message to be easier to read on GitHub as well as in various git tools
You can check Git 50/72: the rule of well-formed Git commit messages which was originally "invented" and promoted by the Linux Kernel team, and gained universal popularity later
🚪 Conventional Commit Type
The type of conventional commit should be one of the following:
• ✨ feat: add a new feature to the codebase
• 📝 docs: changes that update documentation only
• 🐛 fix: fix a bug
• ⚡ perf: changes that improve performance
• ♻ refactor: changes that refactor the code without changing public API
• 💄 style: changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.)
• 🧪 test: adding missing tests or fixing failing existing tests
• 🔨 build: changes that affect the build system or external dependencies (webpack, npm, ..etc)
• 💚 ci: changes to our CI configuration files and scripts (example scopes: config.yml, CircleCI, ..etc)
💫 Conventional Commit Scope
The scope should be the name of the module or package affected such as Crashes, Bugs, APM, ...etc
• Must be nouns
• Provides additional contextual information
feat(parser): ✨ add the ability to parse arrays
📝 Conventional Commit Description
This is where the description of the commit goes, the description can be described as follows:
• It is a brief statement describing the work that was done
• It should be in primitive (e.g. add not adds, adding, added)
fix(parser): 🐛 correct minor typos in code
🦴 Conventional Commit Body
This is where a longer description would go if necessary, you can consider it as a free form, used to explain:
• What are your changes?
• Why you made them?
💬 NOTE: Not all commit messages are complex enough that they need a body, description and type are sufficient
test(api): 🧪 assess test suite quality with mutation analysis
Add a new executable mutation analysis that analyses the API's
test suite and returns a score that we can use to keep track of
how good our tests are at catching defects.
🦖 Conventional Commit Footer
• The footer Should contain any information about Breaking Changes
• The place to reference GitHub or Jira issues and similar
metadata
feat(docs-infra): ✨add v8 to the version picker in the navbar(#35196)
The v8.angular.io should be ready shortly,
so we need to add it to the version picker in the navbar.
PR Close #35196
🔋 Advantages of Conventional Commits
Commits are more descriptive and it's easier to understand them
Types and Scopes make it easy to identify which kind of changes are being reflected in which scope
If you have one action per commit, it´s easier to revert a change or a git conflict
Reduce the burden of managing Versioning and CHANGELOG, now it can be generated by using scripts parsing Commit Message according to type
⛑ Useful tools for Conventional Commits
-
- Provides Lint for Commit Message
- Works with Conventional Commits by default settings
Conventional Commits extension VSCode
- Provides an easy way to add conventional commits in VSCode
Conventional Commit for jetbrains
- Provides an easy way to add conventional commits in Jetbrains
-
- An emoji guide for your commit messages
-
- Automate versioning and CHANGELOG generation, with semver and conventional commits standards