Re:Git-cliff – Generate changelog files from the Git history
by chrismorgan on Sunday September 05, 2021 @07:47PM
(#28428855)
I am a prolific writer of comments and commit messages. It’s not common for me to write single-line commit messages¹, 4–8 lines is probably my most common size, and I’ve gone well above 100 on occasion. At my last place of employment, I think I had 17 of the 20 longest commit messages in the main repository.
I act like this on public and private repositories.
I know others I have worked with have benefited from and appreciated my detailed commit messages, and I’ve even thereby convinced some to write at least three or four decent lines rather than just one bad line.
I myself have certainly benefited from the verbose commit messages that my past self has written.
But here’s the real secret to it: I have benefited by writing these verbose commit messages, even in cases where it’s unlikely anyone (including me!) will ever read them again. You know rubber ducking <https://en.wikipedia.org/wiki/Rubber_duck_debugging>? Commit messages are about describing what you’ve done and why, and the act of writing that down helps you to think about it. More than a few times have I felt the need to justify the approach taken in a commit message, only to realise as I explain it that I had neglected some key consideration so that the approach I used wouldn’t handle certain corner cases, or that a better technique was possible.
I also write changelogs manually, because commit messages and changelogs have somewhat different purposes. And that helps, too, especially in case of deprecation or breaking change, where the changelog should ideally guide the reader in what they should change.
———
¹ Prominent likely exceptions are found in new projects where I’m doing a bit of everything in an unstructured fashion, and commits on my website repository that just add a new article.
I act like this on public and private repositories.
I know others I have worked with have benefited from and appreciated my detailed commit messages, and I’ve even thereby convinced some to write at least three or four decent lines rather than just one bad line.
I myself have certainly benefited from the verbose commit messages that my past self has written.
But here’s the real secret to it: I have benefited by writing these verbose commit messages, even in cases where it’s unlikely anyone (including me!) will ever read them again. You know rubber ducking <https://en.wikipedia.org/wiki/Rubber_duck_debugging>? Commit messages are about describing what you’ve done and why, and the act of writing that down helps you to think about it. More than a few times have I felt the need to justify the approach taken in a commit message, only to realise as I explain it that I had neglected some key consideration so that the approach I used wouldn’t handle certain corner cases, or that a better technique was possible.
I also write changelogs manually, because commit messages and changelogs have somewhat different purposes. And that helps, too, especially in case of deprecation or breaking change, where the changelog should ideally guide the reader in what they should change.
———
¹ Prominent likely exceptions are found in new projects where I’m doing a bit of everything in an unstructured fashion, and commits on my website repository that just add a new article.