Follow Slashdot stories on Twitter

 


Forgot your password?
Close
typodupeerror
×
Linux

Linus Torvalds Asks Kernel Devs To Write Better Git Merge Commit Messages (phoronix.com) 38

Posted by BeauHD from the do-better dept.
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. [...]"
This discussion has been archived. No new comments can be posted.

Linus Torvalds Asks Kernel Devs To Write Better Git Merge Commit Messages More

Linus Torvalds Asks Kernel Devs To Write Better Git Merge Commit Messages

Comments Filter:

  • 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)

      by Anonymous Coward on Monday October 07, 2024 @07:11PM (#64846915)
      I receive where you're coming from.

    • Re: (Score:1)

      by Anonymous Coward

      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)

    by Megane ( 129182 ) on Monday October 07, 2024 @07:18PM (#64846939)

    Passive voice isn't liked by Linus.

    (I can't blame him, I don't like it either.)

    • 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:

      • Don't end sentences on an adpositional. [“What is this for?”]
      • Don't start a sentence with a conjunction. [“So, how are you doing?”]
      • Don't split an infinitive. [”To boldly go where no man has gone before.”]
      • Don't use a dangling participle. [“Driving home

      • 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)

        by CaptainOfSpray ( 1229754 ) on Tuesday October 08, 2024 @04:38AM (#64847615)
        Not at all "USA only".. This is actually an international thing, and a technical writer thing.

        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)

          by psmears ( 629712 )
          No, the anti-passive stigma is much more of a US thing than it is anywhere else, largely due to the influence of Strunk & White. Sure, the passive can be misused, and often is in some circumstances (academic writing I'm looking at you), but it perfectly valid uses too, and avoiding it religiously only makes writing worse.

          • 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)

              by psmears ( 629712 )
              The stigma exists everywhere, but it is much more prevalent in the US. And if the active voice is so much better, why do you say "it is preferred" rather than "people prefer it"? According to what you've written, wouldn't that have far more clarity? As I've said, the passive voice can certainly be misused, but it is absolutely fine when used appropriately, just as it is in your post (and indeed in all of the style guides that rail against it!).

        • 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

          • 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

      • 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 ...

      • 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.

        • I have had the opposite experience. Apparently, developers were being paid to write the shortest possible commit messages. "Fixed " That's it. And if you look at the Jira ticket, it's just the description of the problem.
      • I'm not an expert by any stretch of the imagination, but my understanding is that standardized grammar is a relatively recent thing. After the printing press was invented, there needed to be a way to distinguish the "educated" from the "uneducated" and so lots of fiddly little rules were invented, many transposed from Latin. If you knew the rules your were "superior" to someone who didn't. Then they invented grammar schools to teach the rules to the right people.

      • "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

    • 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)

    by Tony Isaac ( 1301187 ) on Monday October 07, 2024 @09:56PM (#64847109) Homepage

    just to include an actual commit message that goes beyond "Update" or "New code" or even ".".

  • 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....

  • 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.

Slashdot Top Deals

One good suit is worth a thousand resumes.

Close