In a previous article, I wrote about the importance of commit messages and what they should focus on. However, I have some more thoughts about commits. There are a handful of rules and conventions that can elevate further the quality of your commits.
Foundation
There are some basic format rules that every commit should follow:
- The title should ideally have under 50 characters, but these days if you are under 72 is still ok.
- The body is optional, but if there is one, you should separate it from the title with a blank line and each line should have up to 72 characters.
These guidelines allow your code to be shown properly on any git client or tool displaying commit messages.
Even though it's not about format, another basic convention you should follow is to write your title as a command. A good way to test this is to complete the sentence: If applied, this commit will "your title".
These basic rules provide your commits with a good foundation. The next step is to give context to your commits, which is where conventional commits come in.
Conventional Commits
The conventional commits specification define rules to provide context on what your commit does. So you can have commit titles like:
feat(payee): add ability to update contact detailsfix: stop payee manager memory leakchore!: update java version to 21
It allows to easily tell apart feature work, from bug fixes, refactoring, etc. This is primarily useful for automation tools, so that they can:
- Release a version of the software, automatically working out which part of the semantic version to increase.
- Provide release notes highlighting new features and bug fixes, and potentially hiding changes that are not relevant to consumers.
At the same time, it also gives a hint about what a commit is about to anyone looking at the git history.
Scope misconception
A common misconception is how to use the scope (word in parenthesis in the first example). Its goal is to specify what part of the codebase is affected - which can be particularly useful for large monorepos. Instead, it's sometimes used to include a reference to the ticket the commit relates to.
Avoid misusing the scope by using better conventions to provide a ticket reference, as explained next.
Ticket Reference
Most commits are about delivering work that's described in a ticket in your project management tool. Including a reference makes the commit searchable and provides additional context to the reader.
However, it's not the main piece of information you're looking for in a commit message, yet it tends to be added to the title taking vital characters that can be used to explain the actual change.
I'm in favour of including the ticket reference, just not in the title. I suggest you should mention it at the bottom of the text. You can simply add the reference or use a commit trailer format, like:
Fixes: ABC-123Relates-to: ABC-123
Some tools would close tickets if you use the correct format, so look out for it if you're interested in automating ticket status updates.
No reference
There will always be cases where there's no ticket to refer to, so in that case you can simply omit the footer. Still, if you want to automate the validation of your message format, you need to come up with a convention for this case. The following are good alternatives:
Relates-to: N/ANo-ticket: reason for not having one- Require ticket reference only for feature work and bug fixes.
Setting a convention on how to refer to tickets is very important to bring consistency to this topic. Giving credit to everyone who worked on the change is just as important.
Co-authoring
If you do pairing/mobbing in your team, a best practice is to ensure proper attribution by including your co-authors.
As this is a common use case, there's convention to add it as a footer using a commit trailer, like:
Co-authored-by: Luis Mirabal <luis.mirabal@mail.com>
This is supported by many tools so all authors get shown where commit details are displayed.
Besides crediting authors, another useful piece of metadata you can add to a commit are links to external resources. This was a personal source of frustration, as they can be tricky to handle when long and in the middle of the message. In the following section I will provide you with a strategy to manage them.
Links
Long URLs are a common exception to the line length rule, as a working URL is more important than line length. However, placing long URLs directly in the body of a commit message can disrupt the natural flow of the text, making it harder to read.
An approach that solves this problem is to use reference-style links, which keep the main body of the message focused on the text while moving the long URLs to a reference at the bottom. This makes your links look like the following:
See [payee management documentation][1] for complete API reference.
[1]: https://docs.verylongexampledomainname.com/api/payees#update-contact-details
This way, the URL is at the end of the text, and doesn't get in the way of your message. This is rendered nicely if the client supports markdown, yet it's still easy to understand as plain text.
Putting It All Together
Perhaps the most convincing argument for adopting these conventions is to see what a beautiful and informative commit looks like when they are all applied:
feat(payee): add ability to update contact details
Allow users to modify email, phone, and address information for existing
payees through the edit payee form. Added validation for email format
and phone number patterns.
See [payee management documentation][1] for complete API reference.
[1]: https://docs.verylongexampledomainname.com/api/payees#update-contact-details
Fixes: ABC-123
Co-authored-by: Luis Mirabal <luis.mirabal@mail.com>
Following these simple rules, you create well structured commits that are rich in context. Context will make your commits easier to understand for future readers. While structure makes them searchable and enables a number of automation avenues that wouldn't be possible otherwise.
Top comments (0)