I don't particularly want a commit log at the top of every function, TBH. If I'm looking for the history and context of a change, I want to look at the commit log. If I want a description of the current version, I look in the docs (and yeah, sometime I can only piece together why something is the way it is now by looking through how it's changed. But documenting each change has a much better chance of addressing questions like "why did it work and now it doesn't" then trying to get the docs perfect will.)

>I don't particularly want a commit log at the top of every function

If thats what you got from my comment then you misinterpreted it.

Nobody wants docs to look like commit messages. They want them to be relevant to the context.

{Tests, Code Comments, Documentation} are 3 distinct places to trawl through when quickly going through git blame.

The commit message is one place - and gives the author an opportunity to speak directly with a future developer over the place-in-time-context that this change was made.

You're focusing a bit much on the Developers bit. It's not just Developers who are working through the code-base.

As a lame example - Incident Response/SRE will also be trying to get their heads around changes being made - especially if they're responding to an outage, and trying to figure out what change broke production - and why it was made.

Not everyone will know every bit of the project as intimately as the Dev team - and having a good commit message will help any unfamiliar response team mitigate, or escalate accordingly.

You think incident response would also prefer to go digging around using git blame than just reading your docs?

If you put some effort into your runbooks, not your commit messages, thats where they'll really appreciate good, detailed writing.