How to write a good commit message
If you have started your journey to become an experienced developer, you already know that you have to describe what you have done when you change the code and submit it to be merged in the master branch. In git and many other source code management systems, this description is called a commit message.
The commit message has a title, and can have a detailed description. You should separate the description from the title by adding a blank line after the title.
Why it matters to write a good commit message
Some may argue that the code itself is the most important thing, and you should provide a readable clean code. This is true, and you should care most for the code. But, on the other hand, when you are working on a big project with hundreds of developers, it is also important to write descriptive commit message that is easy to read for other developers who work on the same project.
In order to be able to search and find the relevant historical information about different aspects in the code, a good way would be searching in the commit messages. You can invoke:
$ git log
You can press “/” for search, then type a search phrase. By pressing “Enter”, you will get a match, and then the next match by pressing the key “n”. This happens if matches are found.
This is only possible if you and others have previously provided good information on what each change does, providing enough details and keywords, so that others could be able to search efficiently.
If you have added your changes to the staging area of the git, then you can invoke this command to commit the changes.
$ git commit
You should provide a good title and description. Here’s how.
Information Beyond the Commit Message
Git commits also have other information, that are automatically generated. For example, the “Author” field comes from your git settings. You should use your complete first name and surname, and a valid email. Your timezone also comes from your system settings.
The Change-Id is generated when you commit, and it is used to identify a submission across different patch sets. Gerrit adds “Reviewed-on”, “Reviewed-by” and “Tested-by” fields automatically. For example, consider this commit:
Author: Miklos Vajna <vmiklos@collabora.com> Date: Wed Apr 27 20:12:52 2022 +0200 sd theme: add PPTX import for shape fill color effects This is always direct formatting, so FillProperties::pushToPropMap() always has the needed info at hand. Change-Id: I3317b618e0e8bb7688d0f0fbfe4546e2e8b4e947 Reviewed-on: https://gerrit.libreoffice.org/c/core/+/133525 Tested-by: Jenkins Reviewed-by: Miklos Vajna <vmiklos@collabora.com>
Use an informative title with 50 characters or less
You should describe what you have done in a commit in the commit title. The suggested maximum length for the commit title is 50 characters. Also, you should limit the amount of work in a single commit to only one thing. There are many reasons for that; one of them is to be able to roll back your changes with a single git revert.
For LibreOffice commits, you should provide the issue id at the first of the title. For example, tdf#xyz refers to the bug number xyz in the Bubzilla:
Another abbreviation, cid#xyz refers to the Coverity scan report number xyz:
For other abbreviations, please refer to this Wiki article:
You can refer to the module with its abbreviation (sw, sc, etc.) to emphasize the module that the patch is related to. Here is an overview of the modules of LibreOffice.
It is important to keep the title short, because other people can get the whole idea of the change that you have done at a glance. You can see the list of recent changes in this page:
Also, you can pull the latest changes, and use information from git locally, using these commands:
$ ./g pull -r $ git log --oneline --since=1week
The above command lists the title of commits from the previous week.
Provide a Detailed Description
Beyond the title, you should provide detailed description of what you have done in the current commit. You can link to other commits with the commit hash if needed.
Using lists with *, +, – or characters like that can help to provide a better formatting for the texts. For example, consider this commit:
Author: Miklos Vajna <vmiklos@collabora.com> Date: Thu Apr 21 09:08:03 2022 +0200 sw content controls: add insert UI - add an SwWrtShell::InsertContentControl() to put the current selection into a content control - if there is no selection, add a non-empty placeholder - expose this as a new .uno:InsertContentControl uno command - add this new command to the bottom of the form menu -- probably we can have a sub-menu there once there will be more types
Various details are provided as a list. The syntax is mostly similar to the Markdown. Some people argue that the width of the lines should be limited to 72 characters, but there is no consensus on the exact maximum width for line wrapping.
What to Include in the Commit Message?
Include relevant information that can help other developers, including but not limited to:
- Affected modules
- history of the problem, and the solution
- cause of the regression, if this is a fix for a regression
- backtrace (or parts of it), if needed
- references
- any relevant information
How Much Should I Write?
It all depends on you, but please describe what you are doing! Remember that what you write will be read in the future by the others, thus it should describe the changes that you have done in the commit.
Writing a paragraph is the minimum thing that is expected, so the suggestion is that you avoid submitting patches with blank description.
Final Notes
If you want to contribute to LibreOffice code but you need to know how to get started with LibreOffice development, I suggest you to see our Getting started video tutorial.
You can find several easy stuff that you can do inside the code as a newcomer if you follow the keyword EasyHack. I have discussed some of them in this blog and tagged them as EasyHack tag in this blog.
About Author
Hossein Nourikhah | Website | Twitter
Hossein is the Developer Community Architect for The Document Foundation (TDF).