Re: [PATCH v3 02/10] xen/version: Introduce non-truncating deterministically-signed XENVER_* subops

[Stefano Stabellini <sstabellini@xxxxxxxxxx>]

On Wed, 16 Aug 2023, Daniel Smith wrote:
>  > On Wed, Aug 16, 2023 at 3:58 AM Andrew Cooper andrew.cooper3@xxxxxxxxxx> 
> wrote:
>  > On 16/08/2023 1:19 am, Stefano Stabellini wrote:
>  >  > On Tue, 15 Aug 2023, Andrew Cooper wrote:
>  > 
>  >  >> diff --git a/xen/include/public/version.h 
> b/xen/include/public/version.h
>  >  >> index cbc4ef7a46e6..0dd6bbcb43cc 100644
>  >  >> --- a/xen/include/public/version.h
>  >  >> +++ b/xen/include/public/version.h
>  >  >> @@ -19,12 +19,20 @@
>  >  >>  /* arg == NULL; returns major:minor (16:16). */
>  >  >>  #define XENVER_version      0
>  >  >>  
>  >  >> -/* arg == xen_extraversion_t. */
>  >  >> +/*
>  >  >> + * arg == xen_extraversion_t.
>  >  >> + *
>  >  >> + * This API/ABI is broken.  Use XENVER_extraversion2 where possible.
>  >  > Like Jan and Julien I also don't like the word "broken" especially
>  >  > without explanation of why it is broken next to it.
>  >  
>  >  The word "broken" is an accurate and appropriate word in the English
>  >  language to describe the situation.  I'm sorry you don't like it, but
>  >  unless any of you can articulate why you think it is inappropriate
>  >  phraseology, the complaint is unactionable.
>  >  
>  >  Specifically ...
>  >  
>  >  > Instead, I would say:
>  >  >
>  >  > "XENVER_extraversion is deprecated. Please use XENVER_extraversion2."
>  >  
>  >  ... depreciated is misleading.
>  > 
>  > Deprecated means, "It is the official position of the developers of the 
> project that for the moment, you *can* use it, but you *shouldn't*"; it also 
> implies that support for it might go away at some point.  The fact that we're 
> saying "you shouldn't use it" by itself implies that it is lacking somehow.  
> It's a factual statement that gives you useful information.
>  > 
>  > Neither "broken" nor "has problems" actually tell you anything above 
> "deprecated", other than the opinion of the developer writing the 
> documentation; and they are both (to different levels) emotionally charged.  
> You don't deprecate things unless there's something wrong with them.  In this 
> particular case, I don't think anyone has an emotional attachment to the 
> existing hypercall, so nobody is going to be insulted; but it's a good habit 
> to avoid it.  (See [1] for more about this.)
> 
> With all due respect George but deprecated and broken are fundamentally 
> different. Deprecation means that an interface is being retired in the future 
> for any number of reasons and that it can continue to be used until its 
> retirement without risk of unintended consequences. Labeling an interface as 
> broken, which has been acceptable to do so in other much larger communities, 
> is a stronger sentiment that the interface should stop being used immediately 
> because it can lead to unintended consequences, not because it will be 
> retired in some distant future.

No matter what the Merriam Webster would say for the word "deprecated"
and "broken", each individual "absorbs" each word and their meanings
differently.

There are 6 people involved in this discussion including Andrew, and 4
out of 6 didn't react well to the usage of the word "broken" in this
context. For sure in Andrew's mind "broken" triggers the right
meaning and expectations straight away. But for Julien, Jan, George and
me it did not.

We cannot run a representative survey of the developers population to
know which exact word triggers the most appropriate reaction in this
case. Even if we could, it would not be worth the effort.

Instead, I suggest to just go with the majority interpretation among the
participant in this thread and drop "broken" in favor of one of the
alternatives. Such as something along these lines:

"XENVER_extraversion is deprecated and causes truncation. Please use
XENVER_extraversion2.