search

RomuloOliveira / commit-messages-guide

A guide to understand the importance of commit messages and how to write them well
Creative Commons Attribution 4.0 International
6.72k stars 341 forks source link

not follow the rules #54

Open esmaeilpour opened 5 years ago

esmaeilpour commented 5 years ago

Hi, Thanks for your great guide, but I am just curious that why you do not follow some of the rules in you commit messages?

These should use the imperative form, isn't it?

#8b1a1f13a6 #8195c4c08

RomuloOliveira commented 5 years ago

Hey, @esmaeilpour, that's in fact a good question.

First of all, I don't want to add any friction to contributions. Like I've written in the contributing file they are not rules, they're guidelines and I won't nitpick any commit message from any contributor. If they're really really bad I'd just squash the commits into a new commit with a proper message. In the end, I really not caring so much.

If I was in a development team or maintaining an open source code project, however, I'd definitely enforce them and make sure the messages are the best possible. Regarding specifically the imperative form, I'd probably say "hey, I think it's better to write this way, can you do it differently next time?" but I wouldn't make anyone rewrite a message just because of this.

Another reason is that this project is not code. No one will ever look up in the commit history years from now to find out why some change was done in a particular way neither will have to dive into commit history to understand a broader context or how the project evolved. It's really great when a well-written commit message saves a lot of debugging/troubleshooting/researching time explaining the whys that are not written elsewhere. It won't happen here.

esmaeilpour commented 5 years ago

Hey, @esmaeilpour, that's in fact a good question.

First of all, I don't want to add any friction to contributions. Like I've written in the contributing file they are not rules, they're guidelines and I won't nitpick any commit message from any contributor. If they're really really bad I'd just squash the commits into a new commit with a proper message. In the end, I really not caring so much.

If I was in a development team or maintaining an open source code project, however, I'd definitely enforce them and make sure the messages are the best possible. Regarding specifically the imperative form, I'd probably say "hey, I think it's better to write this way, can you do it differently next time?" but I wouldn't make anyone rewrite a message just because of this.

Another reason is that this project is not code. No one will ever look up in the commit history years from now to find out why some change was done in a particular way neither will have to dive into commit history to understand a broader context or how the project evolved. It's really great when a well-written commit message saves a lot of debugging/troubleshooting/researching time explaining the whys that are not written elsewhere. It won't happen here.

You've completely convinced me but I suggest you keep the issue for future questions 😉

retpolanne commented 1 month ago

There's always an XKCD for everything, right?

image

It's really great when a well-written commit message saves a lot of debugging/troubleshooting/researching time explaining the whys that are not written elsewhere.

Take a project like the Linux kernel, where maintainers are really, really, nitpickey about commit messages and patches. Why is that the case there? Because if something breaks, you would want to know exactly what broke, what was the context, reasoning and research behind ones change.

Btw, tools such as git bisect [1] are really great for understanding what caused a bug.

[1] https://git-scm.com/docs/git-bisect

I also believe that, in a world full of LLMs, writing commits with good context will probably help us in keeping documentation alive – documentation fatigue is a thing, so keeping good habits will definitely help you in the future.