Issue #17 - On Writing Good Commit Message
A commit message is worth a thousand comments.
When you make changes in a codebase or add new feature to it, your commit message is the first guide for others to understand what you did and why. If someone else has to work on the code later, they can read your messages and get some idea.
A commit message consist of title and an optional description body. The git command for writing commit message is-
What makes a commit message good can be subjective. For me these are some examples of commit messages which I think devlopers should avoid writing:
And these are some examples which I consider as good commit messages-
When you write commit messages, try to keep these things in mind-
The title of your commit message should always answer WHAT changed.
When you write your message, try to fill up the sentence -
If you use my commit it will <YOUR COMMIT MESSAGE>
Example: If you use my commit it will “fix overlapping of content in mobile view”Or, if you are using past tense-
If you had used my commit, it would have <YOUR COMMIT MESSAGE>
Don’t put large number of files or a big chunk of code under one single commit.
Try to keep your commit message within 72 characters.
Before committing, proofread your message to catch any typos or unclear language.
Use Convention
Conventions are rules that help make commit messages consistent. There are no hard and fast rules for using conventions, and each organization and team may have different rules for writing git commit messages based on their project requirements.
But a common convention that is widely used looks like this-
<type>(<optional scope>): <title>
Example
--------
style(ads): update position of the banner on homepage
Example with a JIRA ticket number
[JK8234] style(ads): update position of the banner on homepageand with description-
<type>(<optional scope>): <title>
[optional description] -> answer why and how
[optional footer(s)] -> may contain reference to PR number, Issues or Jira ticket number
Example
--------
style(ads): update position of the banner on homepage
This adjustment to the ad banner position on the homepage enhances overall aesthetics and user engagement. By optimizing the placement of the ad, we aim to improve visibility and user experience, contributing to a more effective presentation of content.
Closes Issue#27<type> is the category of the commit. Example includes
feat, fix, chore, ci, style, refactor, perf, test, docs,BREAKING CHANGE etcTeam should decide the categories they would allow in the commit message.
<scope> - It’s optional and specifies the module, component or area of the project the commit affects
<title> - Summary of the commit’s purpose. It typically starts with an action verb in present tense.
The benefit of using this particular convention is that release notes and change logs can be auto generated based on the commit type using tools like Github Actions.
Also with a consistent template, developers don't need to spend mental energy deciding how to structure their commit messages, they can focus on conveying the purpose of their changes effectively.
These are some commit messages from the testing library repo jest. As you can see most of the commit messages follow a specific convention.
Writing good commits comes with practice, but it is most effective when you intentionally put effort into conveying your changes in a logical way.
That’s all folks. Thanks for reading!
Insightful read!