Want to stand out in your open-source journey?
This might help you.
If you want to start your journey in open source, then writing good commit messages is a key thing to stand out and improve yourself as a developer.
If you struggle to write good commit messages in your development, you've come to the right place. In this article, we will discuss how to write good commit messages in any project and make your development life easier. So, let’s get started.
Commits are an integral part of any project and having a good commit discipline makes it easier for developers to spot bugs. Good commit history can be useful to understand why the code works the way it does, which also helps prevent bugs.
Here are a few points everyone should follow to write good commit messages as a developer.
Commits must be coherent
It should pass all the test cases. Even if the commit does not pass the test, you first need to fix it before committing it, “fixed the test cases that were caused by the previous commit” shouldn’t go separately in different commits.
It must be safe to deploy individually. If not, then explain properly why it isn’t (maybe use some tag). For example, you made an API endpoint in one commit and then adding the security checks in another commit must be avoided. These things should be there from the beginning.
Error handling should be done carefully. It should be included along with the code that might trigger some error.
TODO comments should be there in a commit (if any) that introduces some other issues or any functionality that is yet to be implemented or any further work is required.
Ideally commits should be small 🤏🏼
Significant refactoring should be done in separate commits from functional changes.
Moving code from one file to another file should be done in a separate commit from functional changes.
Different refactoring should be done in different commits.
Different feature implementations should be done in different commits.
If you find yourself writing a list of things in your commit message for a single commit then you probably should have just done multiple commits.
When not to be small 👍🏻
If you are developing a new feature, you don’t need to split out new commits for every sub-feature of the new feature. For example, if you are building new tools or functionality from scratch, it’s fine to have plenty of options for a new tool/functionality in a single commit. That being said, reviewing 2000–3000 lines isn’t fun, so please be thoughtful about it. You can commit in any way you want in this case but be careful.
Other considerations
If a reviewer feels the commits are overly fine, he can ask the developer to squash the commit to remove any error.
If a commit you write doesn’t pass the test, you should usually amend it and fix the bug in your commit instead of writing a new “fix tests” commit.
Never squash unrelated changes in a single commit.
🚨 Never mix multiple changes in a single commit, but it’s great to include several related changes, each in their own commit, in a single pull request. If you notice an issue that is only somewhat related to what you were working on, but you feel that it’s too minor to create a dedicated pull request, feel free to append it as an additional commit in the pull request for your main project (that commit should have a clear explanation of the bug in its commit message). This way, the bug gets fixed, but this independent change is highlighted for reviewers. Or just create a dedicated pull request for it. Whatever you do, don’t squash unrelated changes together in a single commit.
It might take some practice to get used to writing your commits with a clean history.
How to write Commit Messages? 🤷🏻♂️
A commit message must have two parts:
A summary, which is a one-line overview of the changes.
A description, which provides further details on the changes. It could be anything from telling your idea in short to sharing some resource URL that you’ve used as a reference to write code.
The commit message is a key piece of how you communicate with reviewers and future contributors and is no less important than the code you write.
Below is a detailed example of a few commit messages that I’ve done during my college days.
Example 1
Example 2
I’ve always been a fan of open-source contributions. And, I’ve contributed to a few open-source organizations in my college days. As you can see some of my commit messages are above. It has a summary and description.
🗣️ Here are a couple of things that need to be noticed.
The summary has a tag before the colon specifying which part the change belongs to and after the colon, a one-line overview of the changes. A tag could be anything there is no hard rule for that, it is just part of the product such as any service, or utility name in the backend and a page or screen name in the frontend.
The description of the commit message should explain why and how the change was made. Like a good code comment, it should provide context and motivation that will help both a reviewer now, and a developer looking at your changes a year later, understand the motivation behind your decisions.
Use the commit messages to explain the change this commit is making or the difference between the old version and the new version. Include why the new version is better than the old version.
If you’ve referred to any internet source in your code then add the resource link in your PR description with the info as to why you’ve used it and what is its impact.
Add nfc tag in those commits that don’t affect or change the functionality. For example: fix[nfc]: updated the code comment. Here NFC stands for Non-Functional Commit or Non-Functional Change.
Don’t include details that are obvious from looking at the diff for the commit, such as lists of the names of the files or functions that were changed, or the fact that you updated the tests.
Avoid unnecessary personal narratives about the process through which you developed this commit or pull request, like “First I tried X” or “I changed Y”.
A few examples of good commit summaries 😃
provision: Improve performance of installing npm.tests: Compile Handlebars templates with source maps.ref: Refactored the loop.typeahead: Convert to ES6 module.fix[nfc]: Fixed the typo in a help dialog.<service_name or page_name>[nfc]: Updated the code comment.
As I’ve mentioned above there is no hard rule for tags. You can use tags like add, fix, ref, bug, etc. apart from any product or service name.
These guidelines can surely help you to write good commit messages and make your project’s history clean. I hope you’ve got some idea of writing good commit messages that will enhance your dev experience and will impact you in your open-source journey.
Thanks 🙏🏻
Happy Coding ✌🏻