What really should happen is use of a simple structure with bullet points.

===== Error: Result of Investigation/Actual Problem: Solution:

Thanks for reading!

I actually don't think that structure is better. I consider the most important goal of a commit message to communicate the effect of the change as quickly as possible. I don't think a structure of Error, Result of Investigation, Actual Problem, Solution achieves that.

It's also why I don't think PR templates are generally a good idea except for projects with lots of drive-by contributors. Changes vary so much that a template is going to create noise with so many fields users have to fill out with "N/A" and for some changes, the most important detail of the change won't necessarily be the first field in the template.

> communicate the effect of the change as quickly as possible

This should happen in the title of the PR overall. In larger projects, a single commit is rarely pushed alone. Personally, I use it as a checkpoint to save progress rather than really it being a meaningful piece of work. But then again, I rarely work on projects with lots of people, so this may not be wholly perfect for that use case.

>In larger projects, a single commit is rarely pushed alone.

When I say a commit message, I mean the thing that ends up in the source history when the change is merged. So if you're doing squash and merge, then the commit message that matters is the PR title + description.

For teams that just merge everything including commits like "wip" and "address notes from code review", their commit history is a mess anyway, so they have bigger fish to fry.

I still think that your argument of "conveying most important information first" is really something that should be tackled through the title, but I agree with the rest.

Oh, I agree that the most important information should go in the title. Did I give the impression that it shouldn't?

Perhaps not. On closer inspection, the inverted pyramid reference does seem to support the claim anyways. Sorry! I really need to read better.

Author here.

Happy to take any feedback or answer any questions about this post.

I basically agree with your viewpoint. The commit comment was almost great, but the inversion you describe is an issue.

It's also really common. In all business and technical communications, it's best to make the first sentence or two the tl;dr bullet points (or the ask, if the communication is asking for someone to do something) and have the rest be the more detailed commentary.