5 ms·

I disagree. I want the what. The change itself explains the how. If the why isn't obvious and there's no link to a tracking system that explains it, it's fine

by peepee1982 4y ago

I disagree. I want the what. The change itself explains the how. If the why isn't obvious and there's no link to a tracking system that explains it, it's fine if it's in the message body. I do want the why in comments, though.

KronisLV 4y ago
Personally, I think that the following is a good approach: PROJ-2354 add/modify/remove/... WHAT to implement/fix/... WHY with the code showing the HOW. Ideally, with the commit/merge request having a textual description and/or a list summary for the overall changes, alongside some diagrams/images/gifs/videos, as well as further discussion where applicable. Oh and an issue management system of some sort with the original (business) requirements, notes from requirements engineering, as well as information about testing. Something like architecture decision records (ADR), script snippets, Markdown Wiki documentation or install instructions can also live in the repo. Then, with a decent test coverage and CI setup, it can also be pretty safe to merge the changes, because most of the stuff concerning them will be known and understood. But at the end of the day, there will be as many opinions as there are people. For some, there is no need for longer commit messages (e.g. with multiple lines, like a separate subject/body with explanation) which is more or less my case because that information will be in the merge/pull request. Others will say that filling out merge/pull requests is unnecessary because the commits should have that information (I disagree, but I've heard that stance). Some other people won't even bother with commit messages because in their eyes working code at the end of the day is all that matters (once again disagreed, but we've all seen "code fixes" in the log before). And some will have way different workflows, like not using a web UI of some sort for discussion but instead relying on commit logs and mailing lists. Use whatever workflow feels adequate for you and your colleagues.
- peepee1982 4y ago
  That's how I/we do it. But I don't like long first lines in commit messages, so I'll put the WHY in the commit's message body. And yes, workflow needs to fit the needs of the people working on the project.
Joeri 4y ago
I would go for the combination: first what, then why. Links break, so a link to why is not good enough when it comes to long-lived code. A good commit message should however start by completing the sentence "when committed this will ...". This makes reading the one-line summaries of the git log the clearest to interpret what happened.

KronisLV 4y ago

Personally, I think that the following is a good approach: PROJ-2354 add/modify/remove/... WHAT to implement/fix/... WHY with the code showing the HOW. Ideally, with the commit/merge request having a textual description and/or a list summary for the overall changes, alongside some diagrams/images/gifs/videos, as well as further discussion where applicable. Oh and an issue management system of some sort with the original (business) requirements, notes from requirements engineering, as well as information about testing. Something like architecture decision records (ADR), script snippets, Markdown Wiki documentation or install instructions can also live in the repo. Then, with a decent test coverage and CI setup, it can also be pretty safe to merge the changes, because most of the stuff concerning them will be known and understood. But at the end of the day, there will be as many opinions as there are people. For some, there is no need for longer commit messages (e.g. with multiple lines, like a separate subject/body with explanation) which is more or less my case because that information will be in the merge/pull request. Others will say that filling out merge/pull requests is unnecessary because the commits should have that information (I disagree, but I've heard that stance). Some other people won't even bother with commit messages because in their eyes working code at the end of the day is all that matters (once again disagreed, but we've all seen "code fixes" in the log before). And some will have way different workflows, like not using a web UI of some sort for discussion but instead relying on commit logs and mailing lists. Use whatever workflow feels adequate for you and your colleagues.

peepee1982 4y ago
That's how I/we do it. But I don't like long first lines in commit messages, so I'll put the WHY in the commit's message body. And yes, workflow needs to fit the needs of the people working on the project.

Joeri 4y ago

I would go for the combination: first what, then why. Links break, so a link to why is not good enough when it comes to long-lived code. A good commit message should however start by completing the sentence "when committed this will ...". This makes reading the one-line summaries of the git log the clearest to interpret what happened.