There is a great blog post about it: https://dev.to/jacobherrington/how-to-write-useful-commit-me...
It boils down to the following commit message template:
<what you changed>
because <why it was needed>Out of three (commits, comments, docs), the commits are least approachable, just few changes in the code will erase original commit in the blame.
By all means write good commit messages, but crystallize the info in them into changelog or other docs every bigger release
It's all in addition to the changelog and other documentation if following a defined release methodology.
Personally I like having the "why" in a comment (with a pointer to the bug tracker item) if adding code. That doesn't work as well when deleting code, and for that, the commit message works as well as anything else.
If a what looks like this: Store user full name in session table
The why can look something like this:
The full name is authoritatively stored in the user database and should be looked in using the user name. However, during deploys of the Raticate system, the cache gets invalidated and we need to quickly refresh it. This leads to a thundering herd system, as in incident 5244. By caching the full name in the session table we sidestep this problem entirely.
The reason why the Redis cache was not chosen for this data is because the session object is handed to the checkout system for processing, which can for security reasons, as described in document 7745, not access Redis.
Most developers seem to be poor "commit historians" by default, I'll admit. If you have the energy and consistency to enforce good history, it eventually becomes self-sustaining.
(Those are not the only situations, of course.)
My experience here varies wildly; I’ve worked on projects where commit history was carefully maintained and documented, as well as on projects with random squashing or random commit messages. Both had their own benefits and came with a cost too.
For larger, more complex or more mature projects, going through git history can be a common task. So here I’d prefer meaningful commit messages; git blame/bisect/etc gets easier, and sometimes any additional piece of docs has immense value. For smaller, simpler projects or prototypes, where history isn’t used that often, I don’t care that much.
Source backup is one of my primary uses for SCC, and when I step out for lunch, or need to knock off for the day, I commit where I am, and push with a "wip" (work in progress) message.
The feature branch name I merge is probably the most useful. It's an aggregate of all my commits and what I'm working on.
In fact, even the hairiest long-lived branches can get cherry-picked apart into several "layers" of branches to get reviewed and merged piecemeal. It's really easy if you're starting from too many commits. It gets harder (not impossible) if individual commits commingle said layers.
I find the latter quite common.
Hopefully as a side benefit others also find them helpful, but my present self is always grateful to past-self's conscientiousness!