Message ID | 20170606110556.12922-2-berrange@redhat.com |
---|---|
State | New |
Headers | show |
"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
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 +@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'' +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
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(+)