[Qemu-devel] [PATCH v6 (for 2.10) 0/1] Document deprecation policy & features

["Daniel P. Berrange" <berrange@redhat.com>]

This is a followup to

  v1: https://lists.gnu.org/archive/html/qemu-devel/2017-05/msg02390.html
  v2: https://lists.gnu.org/archive/html/qemu-devel/2017-06/msg01286.html
  v3: https://lists.gnu.org/archive/html/qemu-devel/2017-07/msg00651.html
  v4: https://lists.gnu.org/archive/html/qemu-devel/2017-07/msg04239.html

I would really strongly like to see this documented in time for the
2.10 release, so that we can start the clock ticking on our deprecation
policy and thus actually delete some stuff in the not too distant
future.

The goal is to clarify to users & app developers what they can expect
from QEMU in terms of feature life & any deprecation policy should
it be neccessary to remove features.

The list of features marked as deprecated was determined by looking at
the QEMU source for the word "deprecated'. It was then compared with
the doc Thomas put up at http://wiki.qemu.org/Features/LegacyRemoval

Key differences with the wiki page that Thomas wrote up vs patch 2
in this series

 - Deprecated features are given a fixed lifespan of 2 releases,
   rather than listing deletion at a future "major" v3.0.0 release.
   This ensures that applications like libvirt have a predictable
   fixed amount of time to react to deprecations.

 - Only lists features which are currently officially deprecated,
   no list of possible future candidates. The wiki page is probably
   a good place to maintain a list of future possible deprecations.
   To turn them into actual deprecations, a patch to the QEMU doc
   can then be posted & reviewed in the normal manner.

 - Not listing the '-6' and '-e' args to qemu-img create. Those
   were never deprecations, because the functionality was
   immediately turned into a fatal error. Patches to delete these
   have been merged now

Changed in v6:

 - Remove all discussion of machine types lifecycle since it
   looks like they will be better kept upstream for as long 
   as any downstream wants them (Paolo)

 - Get rid of separate "Support lifecycle" appendix and fold
   its content into the "Deprecated features" appendix (Daniel)

 - Fix s/-monitor/-mon/  (Thomas)

Changed in v5:

 - Removed misleading reference to "major" release (Eduardo)

Changed in v4:

 - Misc typos / wording clarification (Thomas)

Changed in v3:

 - Rename appendix to "Deprecated features" (Markus)
 - List all currently deprecated features
 - Document that deprecated features will be removed after
   2 releases of being deprecated
 - Clarify that clock for removing historically deprecated
   features starts with the forthcoming release.

Changed in v2:

 - Split into 2 patches so we can consider each suggested addition
   independantly.


Daniel P. Berrange (1):
  docs: document deprecation policy & deprecated features in appendix

 qemu-doc.texi | 175 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 175 insertions(+)

-- 
2.13.3