The code is the present truth, the commit messages can inform you about how it got turned into this truth. Interestingly, I recently wrote a short article about this: https://agateau.com/2026/on-commit-messages/
replyYour argument on conventional commits is something I've come to agree with. There are even tools that can generate release notes from conventional commits, and they are premised on the same mistake.
replyThe code can only convey what is being done (and then, in some cases, only superficially). It can't convey what decisions were made, what alternatives were discarded, what business motivations may have led to that code.
replyAnd for old enough code, the author may not be available, or more likely doesn't remember.
Fine, but none of that is in a normal commit message, lets be real...
replyWhich circles back to why it's important for leadership to tackle this
replyYes, but not in the form of commit messages, the parent comment described things better suited to jira tickets, documentation etc.
replyIt feels like we're trying really hard to stretch the utility of commit messages here...
Mainly I was pushing back on: the code is the "truth"
replyI don't feel that is an accurate statement for any complex system.
I don't like complex systems, and I work hard not to create them.
replySure but code can't capture everything. Maybe with enough comments I guess, but not code alone. For example, code won't tell you that this feature was timeboxed hence this edgecase was not supported
replyYou'll at least need the discipline to include the ticket ID in the message. Links to documentation are ok, but they will likely rot and even if they don't the content may change such that it no longer accurately reflects the commit changes.
replyAnd what of the original author is not there anymore?
replyThe world will not end. I’ll get there.
reply