Handling the list of files and functions in commit messages
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. If there's no objections I'll merge that next week.
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
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
participants (3)
-
Anne van Kesteren
-
Michael Catanzaro
-
Ryosuke Niwa