On 06/09/2020 13.56, sebb wrote:
IMO, Git commit messages serve two purposes:
- inform the reviewer why the commit was made:
to guard against spurious commits, they should mention all changes made
- make it easier to find the commit when scanning a file's history
Most messages should be a single line.
Sometimes there is a need for a bit more context to explain why the
commit is being made.
Any longer, and the commit probably mixes too many changes, and should be split.
Git commit messages should not include explanations of how the code works.
Such comments belong in the code source.
It should not be necessary to delve into Git logs to understand why
the code is written as it is.
Depends on how you define "why", I'd argue.
If I have some commentary around why/how I came to write a specific line
of code the way I wrote it, I'd think it's perfectly fine to put that
comment in a git commit body. There is plenty of precedence for that at
ASF.
The alternative would be to it into a new email thread whenever
something is worth noting, and that could get very spammy.
I think it's good practice to put into the code how it works in relation
with other bits, and maybe explain in certain cases why it works the way
it works, so that users can follow what the code does. But I don't think
it's worth putting in the "how I came to this conclusion about how to
write this line of code" segment into every bit of code.
Remember that the ASF releases code as source, so any information that
is necessary for the understanding of the source must be recorded in
that source.
Sebb.
