Patchwork [3/4] QMP doc: Add 'Stability Considerations' section

login
register
mail settings
Submitter Luiz Capitulino
Date Aug. 20, 2010, 7:42 p.m.
Message ID <1282333352-4152-4-git-send-email-lcapitulino@redhat.com>
Download mbox | patch
Permalink /patch/62310/
State New
Headers show

Comments

Luiz Capitulino - Aug. 20, 2010, 7:42 p.m.
Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
 qemu-monitor.hx |   26 ++++++++++++++++++++++++--
 1 files changed, 24 insertions(+), 2 deletions(-)

Patch

diff --git a/qemu-monitor.hx b/qemu-monitor.hx
index 9c27b31..5c1da33 100644
--- a/qemu-monitor.hx
+++ b/qemu-monitor.hx
@@ -35,7 +35,29 @@  information on the Server command and response formats.
 
 NOTE: This document is temporary and will be replaced soon.
 
-1. Regular Commands
+1. Stability Considerations
+===========================
+
+The current QMP command set (described in this file) may be useful for a
+number of use cases, however it's limited and several commands have bad
+defined semantics, specially with regard to command completion.
+
+These problems are going to be solved incrementally in the next QEMU releases
+and we're going to establish a deprecation policy for badly defined commands.
+
+If you're planning to adopt QMP, please observe the following:
+
+    1. The deprecation policy will take efect and be documented soon, please
+       check the documentation of each used command as soon as a new release of
+       QEMU is available
+
+    2. DO NOT rely on anything which is not explicit documented
+
+    3. Errors, in special, are not documented. Applications should NOT check
+       for specific errors classes or data (it's strongly recommended to only
+       check for the "error" key)
+
+2. Regular Commands
 ===================
 
 Server's responses in the examples below are always a success response, please
@@ -1592,7 +1614,7 @@  HXCOMM This is required for the QMP documentation layout.
 
 SQMP
 
-2. Query Commands
+3. Query Commands
 =================
 
 EQMP