5

On my team of 5 coders, we've traditionally adhered to a common git commit message standard stating (only) two rules: commit messages should include the why rather than just the what and they should be written in the past tense.

This is quite loose (e.g., some people prefer writing longer messages, some write shorter ones; some add a trailing period, some do not), and that's okay - I don't think that kind of heterogenity has caused any harm so far. Our main use cases for the commit messages - code reviews and researching the reasons for certain changes or code constructs - are working well.

Recently, one of the team members has expressed a desire to follow the Git repository style, which is becoming a best practice and mandates writing commit messages in present tense, imperative mood, thus contradicting our rules. The rest of the team want to keep using the past tense style, as the imperative style feels unnatural to them.

As the team lead, I'm now wondering, how far does the need for consistency in commit messages go? Is it important that all team members use the same time and mood? What are the arguments against letting some use one style, some the other?

Improve this question
6
  • These posts suggest that the best practice "present tense" Git repository style is mostly applicable to highly distributed projects like Git itself and Linux. See: programmers.stackexchange.com/a/157631/63202, and, stackoverflow.com/a/8059167/471129. Is your project highly distributed?
    – Erik Eidt
    Commented Aug 28, 2016 at 19:01
  • The idea behind only stating the why may be you can do a diff to see the what but it can make the message meaningless and be an unnecessary burden on the developer so I would always start with the what. Having one tense and proper puntuation is good, the history should be a good read, not an irritating puźzle.
    – Martin Maat
    Commented Aug 29, 2016 at 6:10
  • @ErikEidt I didn't actually want to discuss past vs. present tense here, but how important grammatical consistency in commit messages is on a team.
    – Fabian Schmied
    Commented Aug 29, 2016 at 6:27
  • 1
    Someone caring about trailing periods in commit message frankly is procrastinating. There are more important things to be focused on.
    – whatsisname
    Commented Aug 30, 2016 at 21:18
  • 1
    In my experience what's important is how it ties to your task system. So if the commit message starts with (for example) the task id - I've found the actual language and message in the commit to be less important because it's easy to tie to a task which can hold loads more information. I would never worry about tense or grammar in my messages.
    – Allan S. Hansen
    Commented Aug 31, 2016 at 6:46

2 Answers 2

Reset to default
16

Grammatical items such as tense or mood aren't usually important beyond that the message should make sense and be understandable by the team. Making a lot of rules about how to phrase the free-form part of a commit message is probably a sign that the wrong things are being concentrated on.

More important would be consistency in specific syntactic items. For example if you have a ticketing system, having all commits that relate to a ticket have the ticket number in the same place using the same format.

Improve this answer
2

Sometimes people learn about what are commonly agreed standards (conventions) using a certain tool later. It is still better to follow these conventions and adapt the style soon. And everyone should follow once a well-known fact is discovered, because it is annoying to proceed through a list of commits and lose time, because of weird phrasing. Then, there are also tools that interoperate better.

For example, when you use the imperative style the title line which is usually restricted to fit into email subject (about 50 characters plus auto-generated project tags) becomes much shorter and contains only necessary grammatical features (more content, less noise). It makes sense if you use emails as notifications and rely easy-to-read subjects in list views.

Improve this answer
3
  • Actually, I didn't want to discuss the imperative style. My question was whether it's important that, on a team, everyone uses the same grammatical style or not.
    – Fabian Schmied
    Commented Sep 11, 2016 at 18:51
  • I added a few words why following conventions is important. Implies of course that it's good when everyone follows them.
    – Martin Sugioarto
    Commented Sep 11, 2016 at 19:19
  • I like that paragraph about standards/conventions. However, I'm not sure I consider the imperative style a commonly agreed convention, yet - it seems to be quite controversial: stackoverflow.com/questions/3580013/…. What regards weird phrasing, tooling, or conciseness, we (the team, even the proponent of imperative style) do not follow these arguments; past tense messages better match our use cases (log, blame), seem more natural/less weird to us, and only add about 2 characters per verb. But this is a different discussion :)
    – Fabian Schmied
    Commented Sep 12, 2016 at 6:07

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.