As a student, i've always wondered if there is a standard around commit messages. I thought it would make sense for them to be standardised, and when I started my new role I learned about Conventional Commits - and it just makes sense! I see a lot of people don't follow any rules and, when it comes to working with a team, without standardisation the commit log can become quite chaotic and uninformative.
Conventional Commits is a specification for adding human and machine-readable meaning to commit messages. It is a lightweight convention on top of commit messages that provides an easy set of rules to help you create an explicit commit history, making it easier to write automated tools on top of. This convention dovetails with SemVer, by describing the features, fixes, and breaking changes made in commit messages.
Conventional Commits have the following structure:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
With Conventional Commits, there are multiple types of commit you can make.
-
feat:
Add a new feature to the codebase (MINOR in semantic versioning). -
fix:
Fix a bug (equivalent to a PATCH in Semantic Versioning). -
docs:
Documentation changes. -
style:
Code style change (semicolon, indentation...). -
refactor:
Refactor code without changing public API. -
perf:
Update code performances. -
test:
Add test to an existing feature. -
chore:
CHange Outside Runtime Environment - Update something without impacting the code (ex: readme update, CI/CD update...).
Examples
Some examples of the above would be
Commit with no body
feat: allow provided config object to extend other configs
docs: correct spelling of CHANGELOG
Commit with ! to draw attention to breaking change
feat!: send an email to the customer when a product is shipped
Commit with scope and ! to draw attention to breaking change
feat(api)!: send an email to the customer when a product is shipped
Commit with multi-paragraph body and footer
fix: prevent racing of requests
Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.
Remove timeouts which were used to mitigate the racing issue but are
obsolete now.
Story-ref: #1234
Benefits
Readability
Commits are more descriptive, making it easier for teammates and stakeholders to read and understand them. It also makes it easier to contribute.
Changelog
Allows you to automatically generate a changelog.
Version Control
Helps to automatically determine a semantic version bump based on the types of commits landed.
Revert changes
If only one action is made per commit, it makes it simpler to revert a change or git conflict
Top comments (2)
Hello there!
I am glad that you are researching such a things and you are on the right path!
Just one thing i need to say CHORE means change outside runtime environment package.json is actually part of the code itself and can lead to unpredicted scenarios even patches in npm community sometimes can lead to minor or major upgrades due to lack of knowledge unfortunate...
It is even better idea to remove the patch in your package.json for production application since at some point you are not sure which package will be installed and what could go wrong with it.
CHORE is more of an change on lint settings or readme.md or CI/CD settings which are not part of the runtime.
Cheers!
Keep the good work!
Wow I never knew that - I was assuming it was related to chore in English (something that is a menial task that has to be done) - thanks for the clarity!