No Longer My Favorite Git Commit

I just keep my commit messages one-liners and elaborate more on pull requests, where there's enough context to really justify the change.

Putting the message in git puts the information closer to the code, since the pr isn't in git itself but instead the git forge. You can for example search the text of git messages from the git cli, or come across the explanation when doing git blame. I sometimes write verbose commit messages and then use them as the basis for the text in the pr, that way the reviewer can see it easily, but it's also available to anyone who might come across it when doing git archeology
- It obviously depends on your exact git workflow, but my last team had things setup so that the code content of a MR was automatically squashed on merge, and the text if the MR itself was automatically set as the content of the new singular git commit.
  This was largely the best of both worlds because your commits could have almost any text, and the description of what changed could be updated as needed when making the MR. But it ultimately ended up in the git history where it belonged.
  Of course, I still had some trouble trying to get the team to describe their changes well in the MR at times - but that's a different problem entirely.
- Normally when I merge a PR I put the long PR message (if there is one) in the merge commit (again if there is one), rather than shitty Merge PR from patch1 that people seem to use.
  You can actually change the behaviour on GitHub to be sane: https://blog.mergify.com/how-to-change-the-default-commit-message-on-github/amp/
  If I'm not keeping the branch (usually PRs are not big enough to make preserving multiple commits useful) then I squash & merge which gives you the chance to edit the commit message and copy details from the PR message in.

I think you could have just added a TLDR in the beginning of the commit message

At work we always put an issue number (together with a short summary text) in the commit message. The the verbose explenation is done in the issue, where formatting, search and filtering is easier. However this creates a dependency to that issue system.

yeah, trying to convince our product owner to read commit messages wouldn't go smoothly in my team. Some of them love their tickets....
the dependency to the issue system is unfortunate though, I do miss a "decentralized issue system" doing what git does for version control that would just seamlessly integrate with git and have a nice web GUI for less technical folks.
- That's called a mailing list
  /s
I would hate to have to open Jira tickets to be able to understand code or code changes in Git history.
I guess it depends on the quality of the summary. And how usable your issue system is.
I'm sure I would continue to feel uncomfortable though, about the code and history itself not being self-describing. Issue systems change, become unreachable, etc.

That was rather insightful. And I definitely need a primer on writing good commit messages, and possibly on what a good version control commit is in the first place.

And TIL you can actually use some kind of markdown in git commit messages!

You can probably write your commit messages in most markup languages, whether it gets nicely rendered like it does here is a whole other topic
- Me using stars * for italic which renders italic in GitLab but as bold in TortoiseGit

I would dislike the first/referenced commit description as verbose as well. It describes a user or change drafting journey without ever saying concisely or separately what the commit actually does and why. If it at least had that summary up top in a first block or separated with --- separator it'd be much better.

I like the first part of the suggested alternative but I would never put a discovery journey into the commit message, or a "an hour of my life wasted". I would put them in a MR comment - or separated block in the MR description with the intention of it not becoming part of the merge commit description.

The journey is not relevant to the code and changes. When you think of looking at it one year later, you can see the value of a description of the change, but I don't see value in the discovery journey. The journey is more relevant in team-knowledge and workflow of how to work with the code base, and inter-personal team building.

Too much bloat of irrelevant information diminishes discoverability and conciseness of descriptive and useful information. It's noise.