Each commit contains paragraphs of explanatory material. Jeff King's commit messages are "gold standards" to me, often well exceeding the size of the diff itself:
Please folks, I beg of you, spend time writing your commit messages. You're not writing them for you today. You're writing them for others, including your future self. They should explain the commit: What is its goal? Why does it exist? Why was it written in this way? What other context does the developer need to understand this commit?
A PR description is not a substitute for a good commit message for multiple reasons:
1. If the PR is a single commit, then it's just the commit message and your job is probably done.
2. If there are multiple commits, then the PR description should summarize the goal of the aggregate of its commits.
3. The PR description is typically written hours or days after the commit(s). What was fresh in your head when you wrote that code is now stale and you will struggle to recall why you made a change in a particular way more than if you wrote it down fresh when you commit the change.
4. The PR description is not part of the repo's history. It requires access to a (typically propriety) platform to read.
I wonder whether the UI of many git clients contributes to this. Even if very long messages are allowed, from what I've seen typically the dimensions of the fields are fairly small. This could subtly give the impression that you are being too verbose and not using the tool correctly.
Even for git itself it's funny that the article you linked encourages people to learn to love git CLI, but recommends a third party tool for writing multi line commit messages for ergonomics.
Clearly it's not a massive technical challenge, as the good examples show, but the tooling seems to inadvertently encourage shorter messages.
> but recommends a third party tool for writing multi line commit messages for ergonomics.
Suggesting a text editor to edit text rather than trying to type it on the command-line is hardly "funny". If you already live on the command line you don't even need to set anything up as git will launch your $EDITOR for you when you don't specify a commit message using -m, i.e. this is the DEFAULT behavior.
And if you work by making many rapid small commits, rebase and squash when you're "done" and then add the large, longer commit message to the "new big commit".
> 3. The PR description is typically written hours or days after the commit(s). What was fresh in your head when you wrote that code is now stale and you will struggle to recall why you made a change in a particular way more than if you wrote it down fresh when you commit the change.
The PR contains all the back and forth and comments from other people and the backstory on the decision that was made. I'll also periodically add comments to the end of closed and merged PRs after I receive feedback and question days later just to record it all for posterity. You can't do that with git commits because they aren't mutable/fixable documentation.
> 4. The PR description is not part of the repo's history. It requires access to a (typically propriety) platform to read.
It should be "table stakes" to carry your PR history if you migrate between any of the vendors or something self-hosted and they all have import tools which do it for you. This isn't a practical objection in 2022.
I don't see the author there doing any PRs, either though other than for external contributors.
But they're probably an unpaid open source maintainer, so I can't blame them for cutting corners on process to make their own life easier. How much are you paying this person so that you think you can criticize the way they're doing anything?
"A few more minor tweaks."
"A few more minor changes."
"Some extra file-list safety checks."
https://github.com/WayneD/rsync/commits/master
Those are the full commit messages. By way of comparison, here's what commit messages to git itself look like:
https://github.com/git/git/commit/198551ca54f6ff1c95c9357ccc...
https://github.com/git/git/commit/dee8a1455c8ad443ef59e0d5b7...
Each commit contains paragraphs of explanatory material. Jeff King's commit messages are "gold standards" to me, often well exceeding the size of the diff itself:
https://github.com/git/git/commit/aa0834a04e1d9d3ab81ecd4a4a...
https://github.com/git/git/commit/38f865c27d1f2560afb48efd2b...
https://github.com/git/git/search?q=author%3Apeff&type=commi...
Please folks, I beg of you, spend time writing your commit messages. You're not writing them for you today. You're writing them for others, including your future self. They should explain the commit: What is its goal? Why does it exist? Why was it written in this way? What other context does the developer need to understand this commit?
A PR description is not a substitute for a good commit message for multiple reasons:
1. If the PR is a single commit, then it's just the commit message and your job is probably done.
2. If there are multiple commits, then the PR description should summarize the goal of the aggregate of its commits.
3. The PR description is typically written hours or days after the commit(s). What was fresh in your head when you wrote that code is now stale and you will struggle to recall why you made a change in a particular way more than if you wrote it down fresh when you commit the change.
4. The PR description is not part of the repo's history. It requires access to a (typically propriety) platform to read.
So please, https://cbea.ms/git-commit/