Message-ID: <87iko54f42.ffs@tglx>
Date: Wed, 19 Mar 2025 09:08:29 +0100
From: Thomas Gleixner <tglx@...utronix.de>
To: Ingo Molnar <mingo@...nel.org>, Borislav Petkov <bp@...en8.de>
Cc: Xin Li <xin@...or.com>, linux-kernel@...r.kernel.org, Juergen Gross
 <jgross@...e.com>, Stefano Stabellini <sstabellini@...nel.org>, "Ahmed S .
 Darwish" <darwi@...utronix.de>, Andrew Cooper <andrew.cooper3@...rix.com>,
 "H . Peter Anvin" <hpa@...or.com>, John Ogness
 <john.ogness@...utronix.de>, Linus Torvalds
 <torvalds@...ux-foundation.org>, Peter Zijlstra <peterz@...radead.org>
Subject: Re: [PATCH 5/5] x86/cpuid: Use u32 in instead of uint32_t in
 <asm/cpuid/api.h>

On Tue, Mar 18 2025 at 19:20, Ingo Molnar wrote:
> * Borislav Petkov <bp@...en8.de> wrote:
>> On Tue, Mar 18, 2025 at 12:53:05PM +0100, Ingo Molnar wrote:
>> > How is one more word and saying the same thing in a more circumspect 
>> > fashion a liguistic improvement?
>> 
>> Because it removes the "we" out of the equation. I don't have to 
>> wonder who's the "we" the author is talking about: his employer, his 
>> private interests in Linux or "we" is actually "us" - the community 
>> as a whole.
>
> In practice this is almost never ambiguous - and when it is, it can be 
> fixed up.
>
>> I can't give a more honking example about the ambiguity here.
>
> It's a red herring fallacy really. Let's go over the first example 
> given in Documentation/process/maintainer-tip.rst:
>
>     x86/intel_rdt/mbm: Fix MBM overflow handler during hot cpu
>
>     When a CPU is dying, we cancel the worker and schedule a new worker on a
>     different CPU on the same domain. But if the timer is already about to
>     expire (say 0.99s) then we essentially double the interval.
>
> You'd have to be a bumbling idiot to think that the 'we' means an 
> employer or the person themselves ...
>
> Put differently: *the very first example given* uses 'we' functionally 
> unambiguously so that everyone who can read kernel changelogs will 
> understand what it says. Ie. the whole policy is based on a false 
> statement...

That's complete and utter nonsense.

'we cancel the worker, we call kmalloc()' are purely colloquial
expressions. Liguistically they are factually wrong abominations.

We can cancel a subscription, an appointment, a booking...
We can call a taxi, a ambulance, a doctor, ....

But as a matter of fact, we _cannot_ cancel a worker or call kmalloc().

Changelogs as any other serious writing in technical context are about
precision and clarity.

The impersonating form is obviously popular and in some contexts, like
tutorials and beginner guides, it makes them seemingly more accessible,
but that does not provide an justification for using it in the context
of change logs.

Change logs are an important documentation of the underlying code
change, because they provide context and technical justification for the
change and therefore have to prioritize precision and clarity.

Aside of that ,writing a change log in neutral and technically precise
language forces you to actually rethink the problem and the approach to
solve it. Dumping your half baked thoughts in impersonating novel style
does not.

>From 20+ years of experience on the receiving end of the patch fire
hose, I can clearly proof a very high correlation between the quality of
change logs and the quality of the analysis and the resulting code
change.

Yes, it is work to write a proper and precise change log, but that extra
effort makes the work of people, who review patches, easier and it's
also highly benefitial, when analyising historical changes.

Thanks,

        tglx

Powered by blists - more mailing lists