Linus Torvalds Asks Kernel Developers To Write Better Git Merge Commit Messages
([Linux Kernel] 5 Hours Ago
Enhancing Quality)
- Reference: 0001496574
- News link: https://www.phoronix.com/news/Linus-Better-Commit-Messages
- Source link:
Yesterday when announcing the [1]Linux 6.12-rc2 kernel, Linus Torvalds asked that the kernel maintainers do a better job moving forward with their commit messages.
In particular, Torvalds is hoping that kernel maintainers will do a better job using an active, imperative voice when describing the changes within their pull requests.
The Linux creator explained in the [2]6.12-rc2 announcement :
Anyway, on a completely different note: I try to make my merge commit messages be somewhat "cohesive", and so I often edit the pull request language to match a more standard layout and language. It's not a big deal, and often it's literally just about whitespace so that we don't have fifteen different indentation models and bullet syntaxes. I generally do it as I read through the text anyway, so it's not like it makes extra work for me.
But what *does* make extra work is when some maintainers use passive voice, and then I try to actively rewrite the explanation (or, admittedly, sometimes I just decide I don't care quite enough about trying to make the messages sound the same).
So I would ask maintainers to please use active voice, and preferably just imperative.
Put another way: I'd love it if people would avoid writing their descriptions as "In this pull request, the Xyzzy driver error handling was fixed to avoid a NULL pointer dereference".
Instead write it as "This fixes a NULL pointer dereference in .." or particularly if you just list bullet points, make the bullet point just be "Fix NULL pointer dereference in ..".
This is not a big deal, I realize. But I happened to try to rewrite a few of these cases the last week, and I think simple and to-the-point language is better. The imperative version of just "Fix X" is about as clear as it gets.
This would be great for the merge commit messages to be more cohesive as currently the quality of the merge commit messages can vary a lot, especially the quality of the summaries for pull requests during Linux kernel merge windows when all of the new feature code lands but just as well too on the fixes pull requests later in the cycles.
[1] https://www.phoronix.com/news/Linux-6.12-rc2-Released
[2] https://lore.kernel.org/lkml/CAHk-=wgMS-TBfirwuxf+oFA3cTMWVLik=w+mA5KdT9dAvcvhTA@mail.gmail.com/
In particular, Torvalds is hoping that kernel maintainers will do a better job using an active, imperative voice when describing the changes within their pull requests.
The Linux creator explained in the [2]6.12-rc2 announcement :
Anyway, on a completely different note: I try to make my merge commit messages be somewhat "cohesive", and so I often edit the pull request language to match a more standard layout and language. It's not a big deal, and often it's literally just about whitespace so that we don't have fifteen different indentation models and bullet syntaxes. I generally do it as I read through the text anyway, so it's not like it makes extra work for me.
But what *does* make extra work is when some maintainers use passive voice, and then I try to actively rewrite the explanation (or, admittedly, sometimes I just decide I don't care quite enough about trying to make the messages sound the same).
So I would ask maintainers to please use active voice, and preferably just imperative.
Put another way: I'd love it if people would avoid writing their descriptions as "In this pull request, the Xyzzy driver error handling was fixed to avoid a NULL pointer dereference".
Instead write it as "This fixes a NULL pointer dereference in .." or particularly if you just list bullet points, make the bullet point just be "Fix NULL pointer dereference in ..".
This is not a big deal, I realize. But I happened to try to rewrite a few of these cases the last week, and I think simple and to-the-point language is better. The imperative version of just "Fix X" is about as clear as it gets.
This would be great for the merge commit messages to be more cohesive as currently the quality of the merge commit messages can vary a lot, especially the quality of the summaries for pull requests during Linux kernel merge windows when all of the new feature code lands but just as well too on the fixes pull requests later in the cycles.
[1] https://www.phoronix.com/news/Linux-6.12-rc2-Released
[2] https://lore.kernel.org/lkml/CAHk-=wgMS-TBfirwuxf+oFA3cTMWVLik=w+mA5KdT9dAvcvhTA@mail.gmail.com/
mdedetrich