Quality of commit messages


(Darix) #1

Let’s take this as an example. (sorry @tgxworld, this is really just an example, I could have picked so many other commit messages)

I already see you are reverting rails_multisite back to 2.0.4. What I can not see is the why you are doing it. If any of us in a few weeks will look at the gemfile.lock and wonders why is this locked to 2.0.4 … no idea. And as a package maintainer and admin of 2 instances, I have no idea “does the reason for the downgrade affect me? do I need to downgrade too even if I don’t use multisite?”

Can we please aim for commit messages that not just restate what was changed but also explain the why. IMHO statement on what was changed should just be the hook that connects explanation with the change.

I am not advocating to go as far as e.g. the haproxy team (I love their style though). but something that would improve the current situation would be welcome


(Sam Saffron) #2

My advice here is, drive the change you want

If you see a vague or confusing commit message, leave a comment using GitHub, nobody is being vague on purpose and it is super likely people will respond and clarify

Do this enough times and people will develop new habits


(Darix) #3

I did that a few times already in the past, but sure I can do that more
if it is ok for you.


(Sam Saffron) #4

Absolutely fine with me there is a lot to learn from Shawshank redemption, I will let you know if you are overdoing it


(Jeff Atwood) #5

I agree that is a particularly “interesting” commit with no information. But in my opinion those are rare in our codebase, most commits have decent comments.


(Darix) #6

The discussion here illustrates the problem very well:

  1. I get 2 places mentioned where to look for additional information.
  2. Every admin/packager has to know those 2 places to check about the why the version was bumped. There is no link from the version update in discourse to those places.

So instead of one person (the dev who bumps the dep) providing a quick summary, we force all interested users to do the same “work”.

For the same reason it would be good to have the meta links directly in the commit message and not just as a comment on github.

Bump onebox to 1.8.60:
- make instagram icons clickable

Takes maybe 10s longer and makes it easier for fellow devs and users to see why we are doing it.


(Arpit Jalan) #8

I agree that commit message/description could have been better here. I’ll keep this in mind the next time I update onebox version.