Here's my response from the Slack thread:
I almost never leave inline comments on the files or functions that I
change. I write a description of what I'm changing above the file list,
and then I treat the file list itself as just an archaic relic that we
have not agreed to get rid of yet. I write commit messages like this
[1] or this [2] where the file list is just there. I think this is the
most common commit message style among WebKit developers by a lot. I
know some developers carefully fill in the details of what they're
changing in the GNU changelog file list, but I think not many of us do
so.
Detailed commit messages are important and expected of WebKit
contributors (unless the commit is really simple, in which case a
shorter description might be sufficient to explain). But leaving a
commit message in the format of a GNU-style changelog is not useful.
For starters, the changelog format is very hard to read; natural
English is just better. The changelog format also notably encourages us
to say what we are changing in the code, which was useful 25 years ago
when version control was rudimentary and not expected. But that was
already obsolete in Subversion era; nowadays we can all see what is
changing easily from the version control diff, there's just no need to
take the time to explain it as if you can't see. What's more important
nowadays is to focus on why you're making a change, which is something
you just don't have space to do in changelog format, even though the
changelog itself requires a large amount of space and is hard to
read....
So I think we should remove the file/function list from the default
commit message template, and leave it only as a non-default option to
be used by people who like it.
This commit message [3] is my example of an anti-pattern (sorry @Darin
Adler :)
The GNU changelog is really only useful if we want to write commit
messages this way. But it's just not easy to read.
[1] https://github.com/WebKit/WebKit/pull/42640
[2] https://github.com/WebKit/WebKit/pull/40730
[3] https://github.com/WebKit/WebKit/pull/34422
_______________________________________________
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev
