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

[Ryosuke Niwa]

> On May 7, 2025, at 12:39 AM, Anne van Kesteren via webkit-dev <webkit-dev at lists.webkit.org> wrote:
> 
> Keith Miller recently started various discussions about this, the
> latest in #dev on Slack:
> 
>> Have we reconsidered the expectation/requirement to list of changed
>> files in the commit message? IMO, it makes it much harder to read
>> the git log output as most folks don't even put a file-by-file
>> comment in the message anyway. If I care about the history of one
>> file I would just git log Source/foo/bar so that doesn't seem like
>> a good trade off.
> 
> Let me also quote Geoffrey Garen, who provided context for why we have
> this in the first place:
> 
>> My memory is that Darin wrote the original PERL script, and the
>> intention was to provide a structure for per-file comments. If my
>> memory is right, probably nobody will defend the degenerate case
>> where you leave a list of files with no comments. It’s a
>> misunderstanding to explain that git can tell you the same list.
>> That was never the goal.
>> 
>> For commits that explain everything per file, but occasionally
>> don’t explain a file because it’s trivial, probably the best thing
>> is to group the file with other files that get the same comment,
>> or, if the change is truly trivial, remove the file from the list
>> entirely.
> 
> And Darin Adler:
> 
>> [W]e never intended to have people just leave a massive list of
>> files and functions without comments. But few people seemed to
>> understand that; the point of making the list was to encourage you
>> to think about each change and possibly undo changes that don’t
>> make sense, explain each change.
>> 
>> These are decisions we made a long time ago — I do find that my
>> changes are better when I carefully review them and try to explain
>> what I am doing.
>> 
>> [...] If everyone is saying "I just write one comment above and
>> ignore the file and function list" than clearly we don’t need the
>> file and function list. The comments are supposed to say why we are
>> changing things, not what we are changing. [...]
>> 
>> We should definitely delete the file and function list if there’s
>> no comments in there.
> 
> Based on this, I have proposed a change that slightly tweaks the
> advice in the commit message template to make people consider removing
> lines of files and functions without corresponding comments:
> https://github.com/WebKit/WebKit/pull/44932.

This proposed change seems okay. If changes are self explanatory so that no per-function description is needed (e.g. you’re mechanically deploying smart pointers) then it’s okay to omit those. However, I don’t agree with other suggestions made in the same slack thread that the file / function list generation should be optional. I don’t think we should do that. We should encourage people to write per-function comments in commit messages instead.

- R. Niwa