[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [RFC PATCH 1/6] machine: add a deprecated_reason proper
From: |
Philippe Mathieu-Daudé |
Subject: |
Re: [Qemu-devel] [RFC PATCH 1/6] machine: add a deprecated_reason property |
Date: |
Sun, 21 Jan 2018 23:10:48 -0300 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.5.2 |
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.
- Re: [Qemu-devel] [RFC PATCH 1/6] machine: add a deprecated_reason property,
Philippe Mathieu-Daudé <=