This is a team lead/CTO problem. A good leader will be explicit in their expectations that developers write good commit messages. I've certainly had good leaders that expect this.
If I joined a company where people committed their code with "stuff" or "made some changes" or "asdfhlfo;ejfo;ae," that would be a red flag that I might have joined the wrong company, and I'd start to wonder what else the developers here do carelessly.
To put it into numbers: my PRs are usually less than 5 files changed, and very little changes in those files.
A week? LUXURY. I'd be happy to get PRs approved without a week of fighting over stupid trivial nonsense[0]
[0] [flashbacks to the "which way of defining Perl constants is faster" week of hell]
These things never take much time but people dismiss them because of that. Because each commit and each comment in isolation isn't very valuable but they are very helpful in aggregate. I'm not sure why this bias exists though, since the same is true for lines of code. It's also true about a ton of things. All the little things add up. Just because it's little now doesn't mean it's not important
More likely you'd already know by this point because it would be staring you in the face
So we told him to commit at least once every day, with a relevant commit message, or else fail his internship.
He worked 21 more days. There were 21 commits: "17:00, time to go home".
The problem was, as I mentioned, "he though he was the best developer ever". stubborn as hell. And pushed back against anything he wasn't used to, anything that wasn't his usual "ssh or ftp into prod and change stuff until it works" because he thought this was the only method that worked.
This was my first encounter with a self-proclaimed "10x" developer before that term existed. Someone who - as seen by far off management - seemingly have a high output, but in reality just create a trail of tech-debt and work for the rest of the team.
The thing with commit messages is that they are mostly never going to get a lot of scrutiny. But there are exceptions to this; especially if there are audits involved or external contributors. And of course when making a pull request to an OSS project, it is good form to make a bit of an effort. It depends on the context. I tend to focus more on diffs and pull requests. Not on the cryptic one liners that may or may not describe some of the changes. The right unit of change is a pull request, not individual commits.
And all this of course was when I was still able to keep on top of the massive volume of change. With AI that's simply no longer the case and the volume of change is only going to increase over time. Human reviews are now the main bottleneck to getting code merged. AIs probably should be doing a lot of the reviewing, gatekeeping testing, vetting, etc. Especially when AIs also produce most of the change. It's likely a lot of things will slip through unless you get your house in order on guard rails and process that your AI agents need to follow. As a CTO, guarding quality without becoming a human bottleneck is now the main challenge and removing bottlenecks responsibly is part of the job.
BTW. making AI tools write good commit messages is actually be a bit expensive. Many AI tools default to just summarizing the first message of a chat session under the assumption that just one thing changed over the course of a session. Making the AI look at the actual diff is of course possible and not that hard (just ask). And it definitely yields better descriptions when you do that. But it also takes more time and the token cost goes up as well. I'm not sure that's actually worth the expense in tokens. I tend to not bother with this. But again; depends on the context.
Why do you think OSS projects have a high bar for change descriptions? It's because some things matter for the long run.
Also, it's pretty clear from the context of this discussion that it's about the descriptions on pull requests (or other units of change like CLs) and not individual commits that get squashed in a PR/CL.
> BTW. making AI tools write good commit messages is actually be a bit expensive. Many AI tools default to just summarizing the first message of a chat session under the assumption that just one thing changed over the course of a session. Making the AI look at the actual diff is of course possible and not that hard (just ask). And it definitely yields better descriptions when you do that. But it also takes more time and the token cost goes up as well. I'm not sure that's actually worth the expense in tokens. I tend to not bother with this. But again; depends on the context.
All coding agents do that these days - they just run git diff and figure out what the change is when writing the commit message. Are you saying that writing a better change description is not worth the pennies it costs in tokens?
sound like something maybe good commit messages could help with
To the point of other commenters however, I wouldn't lay something this micro at the foot of the CTO in all but the smallest of organizations.
In the company I work for, there is a team that has isolated itself to some extent from other teams and works at a furious pace to keep their particular section of the business happy. We're lucky enough that they spun up their own repo to do their work on, so they don't actually impact other teams, but if the quality of the commit messages is anything to go by, I am 100% certain they're going to end up in a huge mess, if they aren't already. The team lead encourages this, and certainly doesn't care about commit messages etc.
Developers who care about other developers tend to write better quality code, because they care what other developers think of them. If you care about other developers, you will most likely write decent quality commit messages too.
I have seen over many years the types of developers who only care about moving their own code into production as fast as possible and getting to the next thing. There is a very high correlation with a mess at the end, which they inevitably won't have to tidy up because they'll be doing the next thing. These types of developers hate owning stuff in production, so they don't do it, so they don't actually care how maintainable their "clever" code is. I am very certain that a number of people reading this will be those types of developers.
From A Philosophy of Software Design by John Ousterhout:
> Almost every software development organization has at least one developer who takes tactical programming to the extreme: a tactical tornado. The tactical tornado is a prolific programmer who pumps out code far faster than others but works in a totally tactical fashion. When it comes to implementing a quick feature, nobody gets it done faster than the tactical tornado. In some organizations, management treats tactical tornadoes as heroes. However, tactical tornadoes leave behind a wake of destruction. They are rarely considered heroes by the engineers who must work with their code in the future. Typically, other engineers must clean up the messes left behind by the tactical tornado, which makes it appear that those engineers (who are the real heroes) are making slower progress than the tactical tornado.
As a manager, one of the first things I do is make sure that the PR titles (the PR text becomes the commit messages in squash-merging workflows) at minimum begin with a ticket number. Then we can later read both the intention and the commentary on it.
Personally no, the code is the "truth". If I need more I'm going to open a dialog with the author, not spend time trying to interpret a 7 word commit message, "good" or otherwise.
And for old enough code, the author may not be available, or more likely doesn't remember.
It feels like we're trying really hard to stretch the utility of commit messages here...
I don't feel that is an accurate statement for any complex system.
1. What project in general the change was associated with (it may not be obvious from the files changed in this single commit) which can indeed tell you how well it was spec’d- maybe you’ll even find the technical plan.
2. Possibly a hint of how the author intended it to work, or a clue about their misunderstanding. For example, the commit may have changed a function to accept a null argument to “solve” some other problem, but now you know that null passing through here is harmful, well thanks to the commit info, you know that you have to account for the problem that dev was “solving” if you don’t allow the null here. Without that you’d just revert the change and cause the other bug to regress.
Documenting it also forces people to think why they are adding a change in the first place. Code added without purpose becomes dead weight and tech debt.
> It can't convey what decisions were made, what alternatives were discarded, what business motivations may have led to that code.
If you're advocating this should all go in commit messages then I don't know what to say that I haven't already, it objectively doesn't belong there. The end.
Links to ticket IDs are good, and good leaders don’t let old ticket links break on bugtracker migration.
A sentence or so to let future devs know what this change meant to do or at least what initiative it was intended to support, is also good. If future devs (even future YOU) don’t know what you were trying to do, they might revert a change which, without context, looks like a mistake.
Doing both ticket link + text is ideal because someone might screw up the ticket system, and a sentence on its own can be ambiguous.
Doing neither, on purpose, is just willful stupidity. Don’t even bother with Git if you want your commits, the ones that end up in “dev” I mean, to all just say “wip,” “asdf,” and “hope it works now.”
You're thinking like someone with a mature understanding of version control. Plenty of developers seem set on going their whole careers using git like beginners.
Treating simple workflows as inferior is like saying a carpenter is amateurish for not using every attachment in the workshop. Some teams don't have enough upstream issues that they need to lean on git in the way you do maybe?
If enough of the following apply strongly enough to your project:
* Very small codebase
* A one-person project, or a very small team where everyone can be expected know the entire codebase and you don't bother with code-review
* Not doing anything technically challenging
* You don't care about the other advantages of disciplined version-control, such as the ability to meaningfully revert a commit, or to more easily associate a bug with a feature
then sure, you can get away with sloppy use of version control, or even no version control at all. The same applies to various other aspects of software development. Skillful structuring of code doesn't matter in a very small codebase. The drawbacks of dynamically typed languages aren't a real problem in small codebases. Documentation might not be worth writing up. The list goes on. It makes sense that there's generally less call for the various aspects of the 'craft' of software development in such projects. The same applies to other disciplines. You don't bother with CFD modelling for your paper airplane.
I'm not convinced there's really any upside to the sloppy approach though. Developers with the skill to write decent commit messages (plenty of developers lack this), and otherwise make skillful use of version control, tend to make it a habit and always apply the disciplined approach. It's like NASA's old rules for software: The rules act like the seat-belt in your car: initially they are perhaps a little uncomfortable, but after a while their use becomes second-nature and not using them becomes unimaginable. [5][6]
> Treating simple workflows as inferior is like saying a carpenter is amateurish for not using every attachment in the workshop
I see it differently: what I'm proposing is developing mastery over a core tool of the craft, and applying it consistently in our work. We'd expect the same from a competent carpenter or cook.
[0] https://git.postgresql.org/gitweb/?p=postgresql.git;a=log
[1] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/lin...
[2] https://git.ffmpeg.org/gitweb/ffmpeg.git/log
[3] https://github.com/openjdk/jdk/commits/master/src/hotspot
[4] https://github.com/openssl/openssl/commits/master/
[5] https://spinroot.com/gerard/pdf/P10.pdf The Power of Ten - Rules for Developing Safety Critical Code
This is classic dogmatics over pragmatics.
The carpenter understands how to use every tool, they are just pragmatic about its use.
We're talking about low-hanging fruit here. It's not like adopting the MISRA C programming style, which really does severely restrict the programmer.
Torvalds himself writes up proper commit messages even for his toy projects. [0][1] I really doubt it takes him much time or effort. You really think he's not pragmatic?
[0] https://github.com/torvalds/GuitarPedal/commits/main/?after=...
They are useless: Google Messages bothers me to upgrade to a new version. I read the changelog: "Bug fixes and performance improvements". Last time they did it it was full of bugs. Really Google: come back when you actually fixed something.
(This is not an endorsement to do that, he's a good developer in spite of his shitty commit messages)
So, before AI came and saved me from writing commit messages I had alias that ran the whole git add . && git commit -m ... && git push with a fixed commit message. But of course we had squashing so PR title was the one to eventually go there, so maybe that part is fine. But all my side projects had just that.
But I use magit and I can commit specific lines and hunks as easily as files. That helps with managing changes to meaningfully group them.
That's fine until you come up against something like a subscription system that's been built over 15 years by at least 20 different developers, none of whom are currently at the company, half of whom appear to have been clinically insane, each of whom had their own unique approach to code, with almost zero code commentary, zero external documentation, and abstractions layered like geological strata where you need 15 files open to understand one API endpoint.
I though we were talking about good commit messages.