[v2,1/2] docs: document deprecated features in appendix

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 <berrange@redhat.com>

[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.
---
 qemu-doc.texi | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

"Daniel P. Berrange" <berrange@redhat.com> 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 <berrange@redhat.com>
>
> [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
>  
> +@node Deprecations

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

> +@appendix Deprecations
> +
> +The following is a list of features which have been marked as deprecated,
> +pending removal in a future release:
> +
> +@section -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.

On Fri, Jun 23, 2017 at 01:44:46PM +0200, Markus Armbruster wrote:
> "Daniel P. Berrange" <berrange@redhat.com> 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 <berrange@redhat.com>
> >
> > [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).

Assuming this patches continues to get favourable feedback, my
intention was/is to grep the source code for the word "deprecated"
to identify the "full" set, and then send a non-RFC version.


> > @@ -3016,6 +3017,19 @@ Run the emulation in single step mode.
> >  
> >  @include qemu-tech.texi
> >  
> > +@node Deprecations
> 
> Perhaps "Deprecated Features"?  Not a native speaker...

Yep, sounds better.

> 
> > +@appendix Deprecations
> > +
> > +The following is a list of features which have been marked as deprecated,
> > +pending removal in a future release:
> > +
> > +@section -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.

Agreed.

> 
> > +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.

Since the texi is fairly well structured, we could extract the list
of new deprecations from this doc in an automated manner, to populate
the per-release notes.  I'd like to keep the combined list as the
canonical location of the info, so app developers have a single
place to look to find the list, rather than searching multiple
release notes.

Regards,
Daniel