If you’ve been actively using git in your daily work, you might be familiar with the concept of Git commit convention. However, have you considered the potential benefits these messages hold for your future and the success of your team? In this article, I will explain how incorporating Git commit convention into your everyday routine can greatly enhance your team’s productivity.
Quick access:
What does convention mean?
A “convention” refers to a set of agreed-upon guidelines or rules that govern the structure, format, and content of commit messages in a Git repository. These conventions aim to standardize the way developers communicate their changes and intentions when committing code.
How about git commit convention?
When I introduce the concept of Git commit convention to my colleagues, they often ask me why it is necessary to follow a convention. They argue that it is not necessary to follow a convention because they can write whatever they want in their commit messages. However, I believe that following a convention is beneficial for both the individual and the team.
Photo by Cytonn Photography on Unsplash
In terms of collaboration, by following a convention, engineers ensure consistency and clarity in their commit messages, making it easier for team members to understand and navigate the commit history. This consistency is particularly valuable when working in a collaborative environment or when reviewing and debugging code. It helps create a shared understanding among team members and improves the overall maintainability and readability of the codebase. Assuming that you are a developer who has just joined a new team, you will find it much easier to understand the codebase and get up to speed if the team has a convention in place. You will be able to quickly grasp the purpose of each commit and the changes it introduces, as well as the context in which it was made.
On the other hand, when your team build a library, product, or service, it is important to have a release note each time a new version upcoming. By following a convention, you can easily generate a release note from the commit history. This is a great way to keep your users informed about the latest changes and improvements to your product or service.
My favorite convention
<COMMIT_TYPE>: <COMMIT_MESSAGE> (<ISSUE_ID>)
- details 1
- details 2
Signed-off-by: <YOUR_NAME> <YOUR_EMAIL>
- Generalize type of a specific commit by using prefix. For example:
feat,fix,refactor,docs,test,chore, etc… - Use imperative mood: Start your commit message with an imperative verb such as “Add”, “Update”, “Fix”, “Refactor”, etc. This helps to clarify the purpose of the commit.
- Use the body for details: If you need to provide more information about the commit, use the body section to provide details. Use bullet points if necessary.
- Use the present tense: Use the present tense when describing what the commit does, as if you were telling someone what the code currently does.
- Reference related issues: If your commit relates to an issue or bug, reference it in the commit message using the issue number or link. (could be either Jira ticket or repo issue)
- Sign off your commit: If you are contributing to an open-source project, it’s important to sign off your commit using your full name and email address. This helps to track who contributed to the project.
Let’s see what I can do with the above rules, imagine I have these commit messages after running command git log --pretty=format:"%s" HEAD~10..HEAD
chore: minor refactor
test: add test case for gcs dest path builder
chore: refactor mmfp modules
test: add local engine test cases
feat: prepare for 0.3.2 version
fix: hotfix on feature service logic
chore: minor refactor
feat: implement feature service
test: add test case for gcs dest path builder
chore: refactor mmfp modules
feat: add local engine string utils
fix: check fast lane by tag type
test: add engine factory test cases
chore: remove unused modules
fix: no global before_script in ci
fix: coverage report
And now I have this script, which is a simple python script to generate release note from the commit history.
def generate_release_note(commit_messages):
commit_types = {
"feat": "Feature",
"fix": "Bug Fixes"
}
commit_data = {
"Feature": [],
"Bug Fixes": [],
"Stuff": []
}
for message in commit_messages:
commit_type, commit_description = message.split(": ", 1)
commit_category = commit_types.get(commit_type, "Stuff")
commit_data[commit_category].append(commit_description)
release_note = ""
for category, commits in commit_data.items():
if commits:
release_note += f"### {category}\n\n"
for commit in commits:
release_note += f"- {commit}\n"
release_note += "\n"
return release_note
And this is the result:
### Feature
- prepare for 0.3.2 version
- implement feature service
- add local engine string utils
### Bug Fixes
- hotfix on feature service logic
- check fast lane by tag type
- no global before_script in ci
- minor fixes
### Stuff
- prepare for 0.3.2 version
- remove unused modules
- minor refactor
- add test case for gcs dest path builder
- refactor mmfp modules
- add local engine test cases
- add engine factory test cases
Doesn’t it look cool? I can easily generate a release note from the commit history. This is a great way to keep your users informed about the latest changes and improvements to your products.
Conclusion
This maybe looks simple but it is a good start to building up your team’s culture, furthermore, it might boost your team’s productivity as well. I hope you can find this article useful and apply it to your daily basis. Thanks for reading!