The use of Git for us Devs is something essential, whether in personal projects, open source with many people or an entire community.
Given that, it's important that we use git commit properly. Having a coherent and standardized language helps everyone involved in the project to understand the changes that have occurred.
In the image above, we see how harmful a poorly commented commit can be, since we fail to understand the nature of the change that occurred and the context of it. In the long run, the effect is even more damaging, as the maintainability of the software suffers due to inconsistencies in the scope of these changes, and how they have affected the project in the past.
With that in mind, let's talk a little about Conventional Commits Pattern.
What Is It?
Conventional Commits is a simple convention for commit messages, which follows a set of rules and helps projects to have an explicit and well-structured commit history.
How To Use It?
The rules are very simple, as shown below we have a type of commit, the context (scope) of commit and the message (subject) of commit.
!type(?scope): !subject
<?body>
<?footer>
Thus, ! indicates the mandatory attributes and ? indicates optional attributes.
Subject: Imperative instead of past tense
In this way we are telling our team what the commit will do if applied.
“If applied, this commit will ”
“If applied, this commit will change the markup”, which makes a lot more sense than: “If applied, this commit will changed the markup”
Type: What are the types of commits
The type is responsible for telling us what change or iteration is being made, from the convention rules, we have the following types:
test: indicates any type of creation or alteration of test codes.
Example: Creation of unit tests.feat: indicates the development of a new feature for the project.
Example: Adding a service, functionality, endpoint, etc.refactor: used when there is a code refactoring that does not have any impact on the system logic/rules.
Example: Code changes after a code reviewstyle: used when there are code formatting and style changes that do not change the system in any way.
Example: Change the style-guide, change the lint convention, fix indentations, remove white spaces, remove comments, etc…fix: used when correcting errors that are generating bugs in the system.
Example: Apply a handling for a function that is not behaving as expected and returning an error.chore: indicates changes to the project that do not affect the system or test files. These are developmental changes.
Example: Change rules for eslint, add prettier, add more file extensions to .gitignoredocs: used when there are changes in the project documentation.
Example: add information in the API documentation, change the README, etc.build: used to indicate changes that affect the project build process or external dependencies.
Example: Gulp, add/remove npm dependencies, etc…perf: indicates a change that improved system performance.
Example: change ForEach to While, etc…ci: used for changes in CI configuration files.
Example: Circle, Travis, BrowserStack, etc…revert: indicates the reversal of a previous commit.
Note:
Only one type per commit;
The type is mandatory;
If you don’t know which type to use, it is probably a big change and it is possible to split this commit into two or more commits;
The difference between
buildandchorecan be quite subtle and can lead to confusion, so we must be aware of the correct type. In the case of Node.js, for example, we can think that when there is an addition/change to a certain development dependency present indevDependencies, we usechore. For changes/additions of common dependencies to the project, and that have a direct and real impact on the system, we usebuild.
Scope: contextualizing the commit
At this point — and following past conventions — we managed to understand the type of change that was made in the commit (commit type) and clearly understand what the commit will bring if applied (commit subject).
Even though the scope is not mandatory, it can be used to contextualize the commit and bring less responsibility to the subject, making it as brief and concise as possible. Remembering that the scope must be inserted in the commit between parentheses.
Note: Scopes must be separated with /
Conclusion
I wrote this article in order to record one of my learnings (they were just some notes in the notion app), but I hope it can help other devs out there.
Top comments (42)
You can also use gitmoji for this. So your refactor commit would be something like this:
git commit -m "♻️ changed markup"Downside is that you're searching for the right emoji most of the time...Sounds as useful as using ascii art for commit messages. But maybe, if you are fast with your emoji input, it could even be faster than typing a longer word... Or maybe a commit hook could sed "s/^refactor/♻️/" the message for you.
I’ve been thinking about a commit hook that would classify your commit message and then prepends the correct gitmoji. But haven’t found the time to learn about training a model as I’m new to it…
That's the main reason why i don't use emojis or talked about them here... But yeah, you can use them to make a commit look more aesthetic.
I strongly, as of a week or so ago when someone pointed it out to me, recommend not using
git commit -m. It encourages terse, pithy commit messages. In the week since I've banned myself from using it (via a shell function that yells at me when I try), and enforced use ofgit commit -vso I can see the diff in my editor when writing them, I think my commit messages have been greatly improved.or you could've just enabled -v by default.
git config --global commit.verbose trueThat won't prevent use of
git commit -mthough, it just turns on-vwhen you don't use-mto put your commit message on the command line.If you're going for clarity, "feat" should be "feature". The words do not mean the same thing.
Good point, but it's used as "feat" by the convention itself, it's on theirs docs... Check it out later.
Ah, sorry, I thought this was your invention. I will go and annoy them instead 😁
A very nice convention that I've been using this last year, it brings so much clarity and forces me to think about the meaning of what I'm committing.
However, I do not agree with the meaning of "refactor": I always
rebase -ithe code changes after a review. What do you think about it ?Essentially, Git "rebase" is deleting commits from one branch and adding them to another, we can say it's a destructive operation. Usually i prefer the "merge" since it's a non-destructive operation and the existing branches are not changed in any way.
As for the "refactor" the goal is to improve code readability and reduce it's complexities.
The use of them depends on the situation of course, but we shouldn't use only one type of operation.
refactor- A code change that neither fixes a bug nor adds a featureA lot of my commits lately are mostly refactor ;)
rebase -idoes not work on code level. If you rename things, split things, move things, change code flow without changing business logic - that refactor.This is what a new young team lead would come up as an idea or as "a new process to streamline xyz".
Unfortunately, no one will follow these conventions.
With scrum teams, no one really has the time. Instead I would focus on writing proper test cases with 100% functional code coverage.
Tests are surely a must have as well, but once you have the time to implement this commit convention, do it, this helps a lot the future devs that will look at the code.
You have all these information in the attached work item.
I fail to understand how this is useful at all.
Yeah it surely looks pretty but IMHO it doesn't add lot of values.
Someone else from the comments suggest to add emoji!!!. I mean seriously??!
Why waste time on things that doesn't matter or has no purpose.
I will be waiting for your future post on how effective this whole "pattern" is.
THANK YOU!
Despite having just over 3 years in the world of web development, every day I learn something new. It's fascinating! And I didn't know that there were really standards for how to write commits.
I had read some "recommendations", but after reading your post I did some more research, and the conventionalcommits.org site tries to establish a general standard.
Thank you for this information and for sharing it.
Big hugs and blessings from Venezuela.
Our whole team is commited to these conventions. We also built a tool which creates semantic versions/releases following a ruleset. Maybe you wanna contribute or give it a shot-> github.com/AOEpeople/semanticore
You should consider adding a reference to ticket number eventually if you work inside a team. Help a lot with code traceability.
I really wanna see this being used in our work as well, but I will try to use this first myself as I see some Vue.js and Nuxt Github repo's use this structure as well.
Good post 👍🏻
Thank you! I needed this