Better commit messages

[bbatsov]

I was going through the commit history and saw commit messages like:

• adds ...
• added ...
• Add ...

Clearly the project is not employing a consistent style for the commit messages - pretty much every contributor uses a different style for those. Compare this with the commit history of RuboCop.

I believe that all projects can benefit from more descriptive commit messages and a consistent style for them, so I'd like to propose adopting the widely respected guidelines suggested here. Maybe we can add a note about this in the CONTRIBUTING.md (I'd suggest just copying the one from cider-nrepl)?

[benedekfazekas]

I am great fan of meaningful/useable commit msgs see gargamel that said I don't really believe in overinvesting into processes, guidelines. but if @expez @magnars thinks otherwise i wont object.

btw apart from adds/added/add what else do you see violating the quoted guidelines?

[expez]

I think a clean history and good commit messages are important, but I read the guidelines you linked to a long time ago and I think I'm pretty close. If I'm failing miserably then I'd love some more concrete feedback.

I'm not sure what's wrong with Add .... There's quite a few examples of this in the rubocop history as well. These messages all meed the guidelines in the sense that they talk in the imperative and they're all < 50 char long.

[bbatsov]

I'm not sure what's wrong with Add ....

I gave the example because you're using 3 different times for the commit message titles which is not very nice. Also - some commit titles are capitalized and some are not. This might sound like a trivial detail, but it looks sloppy on the outside.

As for bad commit messages - fixes #46 is a good example. Go figure out from your git log what issue 46 was about. Sticking to [Fix #...] ... is a much better idea, I have idea why you're alternating between styles here.

[benedekfazekas]

i don't mind switch to [Fix #...] style. but the issue number is turned into a link for you by github (and by gargamel too ;)) btw just randomly clicking a commit in robocop:
rubocop/rubocop@1eca72d
does not match the original issue title:
rubocop/rubocop#1144

my point is: we can improve on these messages, sure. but let's be concrete what we want to change and don't go tumbling down this rabbit hole of being too strict on what we expect from ourselves and contributors.

[bbatsov]

btw just randomly clicking a commit in robocop:
rubocop/rubocop@1eca72d
does not match the original issue title:
rubocop/rubocop#1144

RuboCop :-) I see the commit matches the issue, so I'm not clear what you mean by this.

my point is: we can improve on these messages, sure. but let's be concrete what we want to change and don't go tumbling down this rabbit hole of being too strict on what we expect from ourselves and contributors.

I'd love to see some consistence and no non-descriptive messages. Don't know about you, but I can be super strict... :-)

[benedekfazekas]

sry about robocop. i guess i fell for the intended pun ;)

i mean the # style issue notation links the issue if you use the appropriate tools (github web/android apps, gargamel, whatnot) adding the title of the issue to the commit (or a paraphrase of it) can be misleading and it is deffo redundant in the above sense.

I'd love to see some consistence and no non-descriptive messages. Don't know about you, but I can be super strict... :-)

consistence i am not super concerned about. but again: if you have concrete suggestions (like instead of fixes #46 use [Fix #46]) i am happy to comply with them. no non-descriptive: i totally agree. I don't think we use any non-descriptive msgs tho (pls note that a simple fix #48 i deem descriptive (while I appreciate that you might not think that is descriptive -- see my first paragraph))

[bbatsov]

i mean the # style issue notation links the issue if you use the appropriate tools (github web/android apps, gargamel, whatnot) adding the title of the issue to the commit (or a paraphrase of it) can be misleading and it is deffo redundant in the above sense.

Sure, but I often use either git log and magit then a ticker references doesn't carry much weight. Anyways, your project - your rules. I'd still suggest adding some CONTRIBUTING.md, though.

[benedekfazekas]

raising the awareness of commit msgs is always good. so thanks for creating this issue.

CONTRIBUTING.md fair point, will do.