Writing good commit messages is an imperfect art. Although there are no specific rules about how to write your commit messages, there are a few conventions to consider. There are good practices, and some standards that would greatly help us along the way. Defining those beforehand and getting used to generate well formatted commit messages will help your developing team perform in more fluid way.
Why is it important?
On one side it does improve the legibility of your project's history. If something goes wrong, let's hope not, you will be able to go back to your log and pinpoint at what time and what might be possibly causing your issues. It might not seem much, but when the moment arrives you will be grateful to have a little well formatted, readable guide of what your team has been going through (a little heads-up, it will happen eventually).
Being able to understand what happened between different releases of your code is quite a challenging task by itself. It is totally worthy to allocate some time to simplify your task.
How to write clean commit messages
Okay, we are all onboard, we need clean commit messages. How do we do that? In order to achieve it, we are gonna use conventional commits. An specification for how to write commit messages. If you are the kind of person keen on diving on documentation, go ahead and visit the website.
As a quick summary. Our commit messages must have a header, that describes what the intention of the commit, with a specific noun, an optional scope and a compulsory description that provides even more context to our changes.
Besides that, you can add a body and a footer to your commits, but they are optional. They will have the following structure:
type [optional scopes]: description
[optional body]
[optional footer]What are the possible types of commits you can use?
| type | function |
|---|---|
| fix | A bug fix |
| build | Changes that affect your build system, gulp, etc |
| perf | Improvements in performance |
| feat | A new feature |
| chore | a task |
| docs | Changes in the documentation of the project |
| style | Related with the style of our app |
| refactor | A restructuring of existing code |
| test | A testing related change |
| improvement | An improvement to an existing component |
The scope should be a name giving us a clear understanding of what is the context of the type applied.
Some examples:
feat(api): cancellations trigger alert message to client
or
fix(core): real time stats charting now in client's local time Some things to remember:
- How long should git commit messages be?
None of ouf commit lines should be longer than 100 characters. It will improve the readability in github, certain tools and editors. - Remember the seven rules of a great commit message
- Any commit that has the text "BREAKING CHANGE:" at the beginning of its optional body or footer section introduces a breaking API change.
- The body should be written in present time tense.
As well as include the motivation and how the realted version of code differs with the previous one. - Funny git commit messages are always welcome, but keep it in mind, you better be funny.
My system uses words to change the status of issues, what should I do?
Most teams nowadays use task management products connected to their commits to keep track of said tasks or their product roadmap. If yours don't, start considering it.
It is great, you can attach GitHub/GitLab activity to your task manager. You or someone in your team has an assigned task. That person push a commit that actually mean said task is ready for review, or maybe it can be even closed. Your task management system picks it up and changes the state accordingly.
The most popular would probably be Github taks. In our case we use ClickUp, because it is great and highly customizable.
The place to use those words is the footer of your commit. An example with body and footer:
feat(api): cancellations trigger alert message to client
It sends a transactional email, letting the client know about the revenue impact of the cancellation
#1axxum[closed]
How to change commit messages
A final note. You work up late, then, next morning you read your Commmit messages from last night and realize they do not make sense (yes, been there, done that). How do we change our commit messages? The usual recommendation is to go through git rebase -i to edit the commit history.
Extra points, generating a changelog from your clean commits
If you are using conventional commit messages, there are a couple tools out there that let you generate changelogs. We use Standard-version, but it you can use Generate Changelog instead.
I hope this little guide helps you write better clean commit messages that are useful and readable. Happy coding!
