Commit messages are whatever an individual, community, or organization decides they should be. Debating beyond that is like debating tabs vs spaces. It doesn't matter as long as everyone you're working with is on the same page.
Nothings worse than digging through a ton of diffs to find the breaking change.
1. really short summary in a few words, ideally mentioning the relevant issue(s) in the bug tracker 2. Blank line 3. Longer message, if necessary, to explain the change
If I'm going to be looking back through commit messages, that's the type of commit message I want to read. I want to know whether this commit is interesting or if I can safely skip it.
It doesn't need to be complicated. Just write a short note as if you wanted to remind yourself where you left off when you come back from vacation.
when we figured out how to avoid a certain type error in typescript, we made sure to describe it in a way that we would find it again, or it would come up in a search.
There's a rationale for every change. The submitter knows it. The reviewer needs to know it. They can try reconstructing it from the diff, which is potentially error prone .. or you could just tell them.
I'll accept "Fix ticket #1234", since that's moved the rationale elsewhere.
the commit history is used for other things too, not just to find bugs using bisect. if that was the case we would not need any commit messages in the first place.
how much effort does it take to explain the change in a sentence? if it is a small change then it also will be a small commit message.
the commit message doesn't need to be nice, but it should be descriptive.
Is it? People assume this, but I'm not convinced they use it for anything else in practice.
> if that was the case we would not need any commit messages in the first place.
I'd be interested in a VCS that followed through on this. Give PRs messages, maybe have some way to attach messages to tags, but permit individual commits to be anonymous.
> how much effort does it take to explain the change in a sentence? if it is a small change then it also will be a small commit message.
More effort than writing the change, often enough. In a high-quality codebase the code change should speak for itself. (And if it doesn't, you may well end up needing an explanatory comment in the code anyway).
that is indeed pretty much true. in that sense the commit message is just helping me to avoid needing to look at the diff. an outline of the commits.
related to the PR, it would then be interesting to annotate groups of commits. a sequence of commits that make up a PR, but even without depending on the current PR mechanism (which at least in git is not stored anyways, so we need something to fill that gap)
tags don't fit that, as they annotate a single commit, and we'd get to many tags that way. some other mechanism is needed to allow treating a series of commits as a unit.
At home I use whatever prettier decides.
At work I just want to do what everyone else is doing so that we are on the same page. Maybe it is weird or something, I really don't care. More important we all work together.
This is like the auto-javadoc software: if the computer can write it from information already in the code, it's a wasteful duplication of time.
Use commit messages and comments for why. Especially if you chose not to do something in a more obvious way for a specific reason. You can't have "self-documenting" for code the version of code that wasn't written.
Sure, commit messages could be mandated to be "whatever an individual, community, or organization decides they should be".
That doesn't mean any of those choices is optimal in absolute terms, or even optimal for the use case of the individual, community, or organization who made the decision.
So it makes sense then to debate what the optimal choice (either absolute, or per use case) is, and this is what the article tries to do.
It would be even better if we had some kind of objective, statistical check on such claims and their pros/cons (e.g. a massive test, with control groups, well defined procedures, and such).
But debating them is also a start, and is needed. If not for anything so that each "individual, community, or organisation" has some input on their decision, and don't just arbitrary impose a format for their commit messages.
I don't even think there is a choice that is "optimal in absolute terms" as you claim. However, consistency within a project is absolutely key and is something we can hopefully all agree on.
It's not "commits as subjects", it's commits as titles. And it doesn't come from viewing the commits through email clients. It comes from needing to know what the commit contains and why was the change done. That is, from having a descriptive title for the change. This is needed whether one checks the commit in their email, on Emacs, on GitHub, or cli.
>As an individual, I might use git to version a blog post I'm writing, and in this case I could use my own entirely individualized semantics for commit messages.
Sure, that's a niche use though, not the use discussed here, which is about commit messages for programming.
But realistically most people today view git through a different client than email, usually github/git CLI. Often, commit messages are the same as PR titles; in that context it makes sense to adopt commits-as-titles. It all comes down to team preference ultimately.
[1] Technically not 100% true these days due to the github mirror
Step 2: be a dick about it.