I noticed more and more commit messages that are not entirely fitting with our CONTRIBUTING.md section on writing good commit messages. In there we state that they should not just contain a brief headline (that is just a copy of the what has been done) but also a bit of information on the reasoning, cross references and such. The obvious exception are trivial package bumps. Very often I see this information only in the PR descriptions.
Personally I prefer having at least as much detail in the commit messages as there is in the PR description. The SCM history is useful for figuring out why a change was made and potentially what lead to that decision. It is also a good place to state trade-offs that have been made etc…
Having access to those information from
git log or often also in combination with
git blame is very powerful. If I had to jump to the browser for every commit that was made to figure out if that is related to what I am looking for that would be a disaster. Worst case the PR would also not contain much detail but was simply waved through.
Whenever I’m reviewing contributions I have been trying to encourage writing proper commit messages. This also extends to the structure of a PR. IMHO we shouldn’t have 20 fixups in a branch for 20 typos.
During a review that I did today a contributor decided to close their PR instead of adding meaningful context (that was only vaguely obvious from the PR description). This got me thinking about the whole topic…
My impression has always been that the guidelines described in CONTRIBUTING.md are the baseline we are aiming for. You can always do better. You can occasionally do worse (I’m guilty of that) but in general you should aim for that and/or above.
Is this no longer inline with what the community see as good practice? Should we enforce this better? What is your opinion? What can we do to improve?