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

["Philippe Mathieu-Daudé" <f4bug@amsat.org>]

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

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.
At least this will force developers to document their deprecations.