> 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 _______________________________________________ webkit-dev mailing list webkit-dev@lists.webkit.org https://lists.webkit.org/mailman/listinfo/webkit-dev
