Re: [Qemu-devel] [RFC PATCH 1/6] machine: add a deprecated_reason property

[Thomas Huth]

On 22.01.2018 03:10, Philippe Mathieu-Daudé wrote:
> Hi Thomas,
> 
>> This series introduces 5 different flavors of deprecation
>> messages:
>>
>> * "Too old"
>> * "Unmaintained"
>> * "The ZCU102 machine has the same features supported"
>> * "Use the \"pc\" machine instead"
>> * "Obsoleted by the \"40p\" machine"
>>
>> Can we clearly document guidelines and examples for values of
>> this field, to help ensure consistency?
>>
>> Examples of questions that could be answered in the field
>> documentation:
>>
>> * Should the message start with an uppercase letter?
>> * Should it really explain _why_ it was deprecated, or is a
>>   simple "please use xlnx-zcu102 instead" good enough?
>> * Which of the following is preferred:
>>   * "obsoleted by the \"pc\" machine"
>>   * "obsoleted by \"pc\""
>>   * "use \"pc\" instead"
>>   * "too old, use \"pc\" instead"
>>   * "too old; use \"pc\" instead"
>>   * <something else?>
> 
> Do you have any preference regarding Eduardo's suggestions?
> 
> I see this pattern:
> 
> - obsoleted by newer
>   -> hint about replacement
> - too old, unmaintained (maybe suggest use an older version?)
>   -> hint when removal is scheduled

I don't mind the exact wording, as long as there is an indication for
the user what to do next (if possible).

> These are also valid for Devices.
> 
> Now if we want a consistent guideline, I suggest we clearly document the
> deprecated machines/devices in qemu-doc.texi and extract this
> information at build time, like trace.h.

While it's a must of course to document deprecations in the qemu-doc,
automatic extraction already sounds like over-engineering to me. I don't
think that we are going to have as much deprecation entries as trace
points, so would an additional automatic mechanism really help a lot here?

 Thomas