I have stumbled upon the short post that contained the following:
~200 lines of commit message for +5/-8 change @ #FreeBSD: https://freshbsd.org/freebsd/src/commit/9a2fac6ba65fbd14d37ccedbc2aec27a190128ea
This obviously made me think. Is such a long description necessary? And if it is, is the commit message description the right place to put it in?
Is a long commit message description necessary?
I could rationalize the answer to the first commit description rather easily. Yes. Yes, it is necessary to document changes in anything. No excuses. If the description of the change is so complex, be it so. Kudos to anyone who makes great work.
Is the commit message description the right place?
This question was more tricky. The reason is that there are multiple places where the detailed description could be placed. Apart from the commit message description itself, the changes could be documented in the code comments or a Pull Request (or a Merge Request, or equivalent). Let's break it down a little bit.
Putting change description in the code comments was a practice before version control systems with the possibility of a adding a change message was a commonplace. The times are far gone. It is still worth to put details in the comments, but they should not interact or rely on other comments. With a description such long as this one, spanning multiple lines, this probably is not a good idea.
On the other hand, putting the details in the Pull Request could also be worth, but there it could be changed quite easily and important parts of the description could be lost, especially because code hosting platforms that offer the Pull Request or a Merge Request functionality do not offer it as a standardized feature, meaning it could be there today but disappear tomorrow.
Linking between the descriptions
There is one other aspect of this all. It is possible to insert a link to either the commit message description, into the Pull Request or even into comments. Which one should be the canonical source?
Thinking about it, the commit message description it the best place, especially if backed by the code hosting platform, that generates persistent links to the commits and their descriptions. Creating a detailed commit message description and linking to it everywhere else is the way that the description with important bit and reasonings is not easily lost, as changing a commit history is a very discouraged practice.
This practice is similar to POSSE (Publish (on your) Own Site, Syndicate Elsewhere), although in the content creation context. But the code and it's messages are becoming the content too, so it probably makes sense to start treating it as such. Put the canonical commit change notes into the commit message description and link to it (syndicate) from elsewhere.
This is a 69th post of #100daystooffload.