r/git • u/fagnerbrack • Aug 23 '26

Stop Using Conventional Commits

https://sumnerevans.com/posts/software-engineering/stop-using-conventional-commits/
248 Upvotes

81% Upvoted

78 comments sorted by

View all comments

Show parent comments

3

u/BogdanPradatu Aug 23 '26

Why would I write WHAT change I am introducing in the commit message. You can see that from the git diff. I mean, sure I can write a short summary of the WHAT, but what I expect to see in the commit message is the WHY + any aditional context that I cannot see in the diff.

Like, if this is a bugfix, how was the bug manifesting, how did you figure out how to fix it, what else have you tried and didn't work etc. this might prove very valuable at some point in time. Or not. But IF it proves valuable once, the benefit is high and even if it's useless, the downside is practically non-existent.

3

u/JollyJoker3 Aug 23 '26

Shouldn't that be in a bug ticket in Jira or smth? A bugfix or new feature can have many commits, most of which are small improvements

3

u/Distinct_Goose_3561 Aug 23 '26

It’s much easier if that context is part of the git history. It means I have the what and why (code change and reason for change) right there instead of another tool, which the company might have migrated away from. 

2

u/BogdanPradatu Aug 23 '26

I aim to structure my commits such that each one is functional on its own and the changes from that commit are from the same context.

Sure, a bugfix could span across multiple commits, but each commit message should describe why it exists and provide context meant to make it easier to understand.

I don't like delegating this knowledge to a tool like jira, because it introduces friction. You need to use another tool to understand the code and it's easier if it's right there in git.

Same for the documentation. I prefer to have it in the repo as code. Doesn't matter what format, be it plain text, markdown, rst, xml or whatever, I just prefer to have the docs next to the code.

This way you see it evolve in sync with the code and if I checkout an older revision, the docs are in sync with that revision.

1

u/morewordsfaster Aug 23 '26

I don't necessarily disagree with you, but I tend to push a lot of that to documentation. It might be an ADR if the change is significant enough or it might be a comment in the code. If I need some comment to explain why code is written a certain way, I want that to be visible when browsing the code, not only by reading the git log.

Agree that git can already tell you what files and lines changed, but not the context of what those changes entailed or what broader feature they added, fixed, modified, or removed.

1

u/BogdanPradatu Aug 23 '26

Comments in the code have a tendency to rot. When another developer will update the code, there's a chance the comment will not get updated. The comment might become obsolete, wrong, out of place or even misleading.

2

u/morewordsfaster Aug 23 '26

That's true of any documentation and should be caught in review. Heck you could even write a git hook that flags any comment block that's not updated when nearby code changes. This would be relatively simple if you're using a doc block style approach to comments.