[webkit-dev] Handling the list of files and functions in commit messages

[Michael Catanzaro]

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