Linus Torvalds Asks Kernel Devs To Write Better Git Merge Commit Messages (phoronix.com) 38
Phoronix's Michael Larabel reports: Yesterday when announcing the 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 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. [...]"
The Linux creator explained in the 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. [...]"
Re: (Score:3)
Do go on to explain how Torvalds asking that commit messages be somewhat "cohesive" is strange.
Re: (Score:2)
That there is not really a technical angle. When reading "better git merge commit messages" I expected it would be that the devs did not write useful contents, nobody could understand. But in the end it's just that Linus has his own style of typographical bullets and grammatical voices. I mean great, I understand the concern (a consistent style means it's probably a split second faster to parse and therefore a bit lower mental load for those reading many of such commit messages), but it's not much technical
Re:Wow what a strange story for a front page (Score:4, Insightful)
... But in the end it's just that Linus has his own style of typographical bullets and grammatical voices.
Well, he does clarify a bit when he says "But what *does* make extra work is when some maintainers use passive voice". To my way of thinking that's more than a stylistic quibble. It's a way of helping to maintain a culture that isn't passive - or worse, passive-aggressive. Coding and documentation require directness, explicitness, and clarity. The passive voice runs counter to that.
Re: (Score:3)
Re: Wow what a strange story for a front page (Score:1)
Re: (Score:2)
Not really. It's about Linus Torvalds (insuring that it makes it to the front page of our open source techie site), and it's also about Git commit comment formatting (insuring an argument about proper Git commit comments in the discussion forum).
The only way it could be better is if it included a comment badmouthing Microsoft or praising cryptocurrency, which would then make it the perfect Slashdot post.
Re: Wow what a strange story for a front page (Score:2)
Then next.. (Score:2)
Eliminate any use of "get" from the text if it doesn't mean "to receive" and use the proper English terms for it.
Re:Then next.. (Score:5, Funny)
Re: (Score:3)
I very nearly didn't receive that joke.
Re: (Score:1)
Eliminate any use of "get" from the text if it doesn't mean "to receive" and use the proper English terms for it.
Like most words, proper English has more than one definition of "get". We aren't in grade school any more.
tl;dr (Score:5, Funny)
Passive voice isn't liked by Linus.
(I can't blame him, I don't like it either.)
Passive voice by Linus liked isn't (Score:2)
Saying, just.
Re: (Score:3)
Why do I so often read this culture in English of avoiding the passive? As far as I understand this is a purely U.S.A. thing where a lot of other stylistic or grammatical advice is given which seems inane to me such as:
Re: (Score:2)
Why do I so often read this culture in English of avoiding the passive?
Because it often reads like crap. It's usually longer, more convoluted and gives the impression that the thing in question just sort of happened on its own and the person doing it was merely there as an observer as the action mysteriously unfolded.
thing where a lot of other stylistic or grammatical advice is given which seems inane to me such as:
Yeah those are mostly silly. Split infinitives particularly so. The dangling participle one h
Re:tl;dr (Score:4, Informative)
Passive voice conceals who is acting. "The value must be set before running the program". Who is supposed to set it? The installer? The user? God?
Passive is harder work for the reader, and much harder for non-native speakers. Which is why use of passive is behind a lot of the complaints about "your documentation is unusable".
If you want to be understood, write in active voice.
Re: (Score:3)
Re: (Score:3)
No, the anti-passive stigma is much more of a US thing than it is anywhere else
False. There are literally countless style guides out there that say to not use passive voice. Active voice is more direct and concise than passive voice so it is highly preferred in any technical situation especially when passive voice typically permits a sentence with far less clarity than active voice.
Re: (Score:2)
Re: (Score:2)
Not at all "USA only".. This is actually an international thing, and a technical writer thing.
I disagree. These rules are known to pretty much only be taught to secondary school students and both native speakers and second language speakers in many countries never encountered them. They're infamous for pretty much purely being isolated to U.S.A. curriculum and simply being silly because the intuition of no English native speaker is offended when he sees the passive. There is no historical basis to it.
Passive voice conceals who is acting. "The value must be set before running the program". Who is supposed to set it? The installer? The user? God?
This is an excellent use of the passage exactly because it is irrelevant who sets it, the only requi
Re: (Score:2)
This is an excellent use of the passage exactly because it is irrelevant who sets it, the only requirement is that it be set before running the program, who does it, and how it is achieved doesn't matter.
Actually it does. On a fundmental level you've just written a technical requirement which is ambiguous to its implementation. Even if it doesn't matter for the program it does matter for consistency within the context of a wider engineering problem, especially when different people work on the same set of requirements.
What you're saying is precisely the reason many IT contracts run massively over. There's an implication that something must be done, but not clear guidance as to by who or how. The result is i
Re: (Score:2)
https://slashdot.org/~Ongeloof... [slashdot.org] has completely missed the point.
Re: (Score:1)
Don't end ..., Don't start ..., Don't split ..., Don't use ..., are direct and to the point. Imperative, I believe.
Sentences ending on an adpositional, whether recognised, are less appreciated, when seen or sat on.
So get this, the problem with beginning a git comment with conjunction is that I already forgot the point by the time ...
Re: (Score:1)
I am curious where long commit messages that avoid a point are most appreciated. I worked with an Indian team for a year who were clearly paid by the commit message word:
This commit will satisfy the requirements as specified by the task as per custom that was assigned during sprint and now ready for approval to be submitted to test environment for user acceptance.
Re: (Score:2)
Re: (Score:2)
Re: (Score:2)
"Why do I so often read this culture in English of avoiding the passive?"
Because it is indirect, making the sentence less vigorous and vivid, and de-emphasizes the actor (and can omit him altogther). "Jack murdered Jane" makes it abundantly clear that Jack is to blame. "Jane was murdered by Jack" is less direct. "Jane was murdered" leaves out important information altogether.
"Don't end sentences on an adpositional. [âoeWhat is this for?â]"
That is something up with which I shall not put!
"Don't s
Re: (Score:1)
This is a comment written in ASCII meant to agree with Megane in so far as long meta messages that write much but say little are, some in the software development community including the author of this comment might say, worse that passive voice alone.
Many developers are doing good (Score:4, Insightful)
just to include an actual commit message that goes beyond "Update" or "New code" or even ".".
Re: (Score:3)
https://xkcd.com/1296/ [xkcd.com]
Most developers don't have the concept of cleaning up commits before a merge request, kernel people do.
English is not good at ambiguity. (Score:1)
English deals deals with tense and instance. All the ambiguity is merged from other root languages and ironically is often an intellicetual way to tell the listener no point is as of yet forthcoming....
Nothing wrong with a style guide... (Score:2)
But you probably need to make it more concrete than just a few guidelines and have lots of examples.
I think any large open source code base should have style guide for commits, pull requests, initial review and so on. The constraints actually make it easier to write such things, I think.