Worked example - Writing better commit messages
Adding references and explanations to commit messages to help other developers understand your reasoning
Photo by Daria Nepriakhina on Unsplash
In my experience, many developers write very short git commit messages, and give little thought to providing helpful context for other developers in the future who may read the message. While I'm happy to write a short commit message if that's all that is needed, I am a big proponent of longer messages where extra context is helpful. Consider the following situation:
I recently upgraded some projects in a large .NET solution. Some projects in the solution had been targeting .NET Core 3.1 (<TargetFramework>netcoreapp3.1</TargetFramework>
) and others had been targeting .NET Standard (<TargetFramework>netstandard2.1</TargetFramework>
). The data access was being done with EF Core 3.1. I updated all projects to use .NET 6, and upgraded EF Core to version 6.
What would you have written as a commit message? I suspect a lot of developers would write something minimal like .NET6 upgrade
. This is the commit message I actually wrote:
upgrade: Retarget all .NET standard projects to .NET 6, and update EF Core to v6 in those projects.
.NET 3+ fully implements .NET Standard 2.1 so this is safe - dotnet.microsoft.com/en-us/platform/dotnet-..
.NET 5+ replaces .NET standard for code sharing so is a better approach for us - devblogs.microsoft.com/dotnet/the-future-of..
EF Core 6 is only available in .NET 6 - docs.microsoft.com/en-us/ef/core/miscellane..
This upgrade gives us a single target for all projects, and a single version of EF Core for all projects.
Notice 3 things about this commit message:
- The first line is still a succinct summary of the work. It is not necessary to read the whole message to understand what this commit contains. The first line provides enough information for a reader to know whether or not this commit is relevant to them.
- I provided references for my assertions about versions. It's not reasonable to expect that all developers who work with this code in the future will be familiar with the ins and outs of .NET versions. If this commit is relevant to them for any reason, they need to be able to find the information which places this commit in its broader industry-wide context.
- I include the motivation for the change (which in this case was consistency across all projects).
What do you write in your commit messages? Would you have included anything I missed here?