Alexey Nikitin, (Nikitin 2019)
Summary
A response to David Thompson | My Favourite Git Commit which asserts that git commit messages are less useful when compared to testing and more-accessible documentation (e.g. a README).
Thoughts
Notes
The essay isn’t written in English. I’ve used Google Translate to read and quote.
Commit messages do not help to find problems and their causes
[…] very often I cannot find the commit in which the change I need was made. First, on a line that works erroneously, there are usually several commits, and you need to look at everything. Secondly, this line could be copied from somewhere, in which case its history will be lost.
git log[is a] powerful tool, it can be used to find a commit by a . But ask yourself a question: will you run a gitcommit search if you have an encoding error in your project when executing scripts? No. Most will answer that they will open google , or immediately [Stack Overflow] and there they will look for a solution to the problem. In this case, nonegit logwill help, because this is not the tool that is used to find solutions to a problem. Although I have no doubt that the author of the commit is a smart guy, and gathered the right information to find the problem with encodings.
How could you have done
Test
The very first thing that came to my mind was a test. Write a test that will check for new such errors in the project (Den should have written a bash test that would check the encoding in the project files before running all the tests). When configured, CI is a powerful tool for future project participants. If someone in the future wrote one / several (yes, even the entire file) in a different encoding, then he would be stopped by a test that would kindly report the accepted encoding in the project - checkmate.
Documentation
The accepted encoding is a disciplinary rule in the project. Since the project has readme, it was possible to add a paragraph there about the accepted encoding and possible problems if you deviate from this encoding. After all, new people enter the project just through reading readme(usually it says how to run, which versions to use, possible errors, even the changelog of versions can be seen there). Then, faced with a similar error, the project participant would definitely remember the accepted encoding and fix the problem. Leaving documentation of the project discipline rules in commit messages would not have the same effect.
A commit message to change a single character is hard-to-find information. The project once paid for this information, but now it’s worthless, floundering uselessly in a sea of 27,000 commits. And the project will have to pay more if a similar problem shoots in the future.
Long commit messages degrade maintainability
If you are tempted to write a whole story in a commit message, you should think about how you can provide this story in another way - tests or documentation are much better. Having to read commit messages in order to find and fix a problem is not a sign of good code.