On May 7, 2025, at 12:39 AM, Anne van Kesteren via webkit-dev <webkit-dev@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