Re: [Qemu-devel] [PATCH v2 1/2] docs: document deprecated features in appendix

[Markus Armbruster]

"Daniel P. Berrange" <address@hidden> writes:

> The deprecation of features in QEMU is totally adhoc currently,
> with no way for the user to get a list of what is deprecated
> in each release. This adds an appendix to the doc that records
> when each deprecation[1] was made and provides text explaining
> what to use instead.
>
> Signed-off-by: Daniel P. Berrange <address@hidden>
>
> [1] This is a lie. I've only listed one deprecated feature. Once
>     we agree on the general concept, we can fill out the doc
>     with the rest of the currently deprecated features.

As written, this is PATCH RFC.  We can either collect the currently
deprecated features before we commit (with the footnote dropped), or
collect later (but then we should note the incompleteness in
qemu-doc.texi, not just the commit message).

> ---
>  qemu-doc.texi | 14 ++++++++++++++
>  1 file changed, 14 insertions(+)
>
> diff --git a/qemu-doc.texi b/qemu-doc.texi
> index 965ba59..29f89d8 100644
> --- a/qemu-doc.texi
> +++ b/qemu-doc.texi
> @@ -37,6 +37,7 @@
>  * QEMU Guest Agent::
>  * QEMU User space emulator::
>  * Implementation notes::
> +* Deprecations::
>  * License::
>  * Index::
>  @end menu
> @@ -3016,6 +3017,19 @@ Run the emulation in single step mode.
>  
>  @include qemu-tech.texi
>  
> address@hidden Deprecations

Perhaps "Deprecated Features"?  Not a native speaker...

> address@hidden Deprecations
> +
> +The following is a list of features which have been marked as deprecated,
> +pending removal in a future release:
> +
> address@hidden -drive boot=on|off (since v1.3.0)
> +Since release 1.3.0, the ``boot=on|off'' parameter to ``-drive''

I wouldn't repeat "since v1.3.0".  It'll get old quickly when the list
grows.

> +is no longer honoured. It is currently ignored, but a future verson
> +will reject this parameter with an error. Applications should use
> +the ``bootindex=N'' parameter to set an absolute ordering between
> +devices instead.
> +
>  @node License
>  @appendix License

I like it.

Of course, new deprecations need to be in release notes, too.  If the
duplication bothers us, we could perhaps just point to release notes.
We'd have to check and amend old release notes to make sure all
currently deprecated features are covered.