We should fix the following issue in qemu-events.txt before we ship
it: we document event BLOCK_JOB_ERROR members __com.redhat_reason and
__com.redhat_debug_info.  We need to take them both out, because they
aren't available in other versions of RHEL.

Fix included in qemu-kvm-1.5.3-90.el7

Hi Miroslav,

Checked the /usr/share/doc/qemu-kvm/*qmp* in version:
qemu-kvm-1.5.3-90.el7.x86_64

[root@amd-5400b-4-4 qemu-kvm]# pwd
/usr/share/doc/qemu-kvm
-rw-r--r--. 1 root root  70528 Jun  4 14:19 qmp-commands.txt
-rw-r--r--. 1 root root  15112 Jun  4 14:18 qmp-events.txt
-rw-r--r--. 1 root root   9945 Aug 27  2013 qmp-spec.txt


Here are some problems / confusions I found, could you help confirm them?

1. qmp-events.txt:

(1) I think it's better if there is an introduction at the beginning of the doc, which won't makes you feel sudden of the doc.

(2) About the event, the format should be like:
{ "timestamp": { "seconds": json-number, "microseconds": json-number }, "event": json-string, "data": json-object, }

instead of

{ "event": json-string, "data": json-object,
  "timestamp": { "seconds": json-number, "microseconds": json-number } }

2. qmp-spec.txt:

(1) Same problem as qmp-events.txt under "2.5 Asynchronous events"
{ "event": json-string, "data": json-object,
  "timestamp": { "seconds": json-number, "microseconds": json-number } }

3. qmp-commands.txt:
There are 3 parts in qmp-commands.txt:
Introduction, Regular Commands, Query Commands.

But there are some regular commands were added under "3. Query Commands", which is a little confused for the reader.
e.g. blockdev-add, chardev-remove, chardev-add


Thanks.

Thanks for reviewing actual contents, not just presence of the
documentation files.

Since this bug is about their presence, I suggest to let it pass QA,
and file separate bug(s) for contents problems worth addressing (if
any).


> 1. qmp-events.txt:
> 
> (1) I think it's better if there is an introduction at the beginning
> of the doc, which won't makes you feel sudden of the doc.

The introduction is in qmp-spec.txt.  We could add a paragraph to the
beginning of qmp-events.txt pointing back to it.

If you think something like that is worth doing, please file a bug
against RHEL-7 qemu-kvm-rhev, and we'll take it from there.

> (2) About the event, the format should be like:
> { "timestamp": { "seconds": json-number, "microseconds": json-number }, "event": json-string, "data": json-object, }
> 
> instead of
> 
> { "event": json-string, "data": json-object,
>   "timestamp": { "seconds": json-number, "microseconds": json-number } }

Both forms are equivalent, as the order of members in a JSON object
does not matter.  Any particular reason for wanting another order
here?

> 2. qmp-spec.txt:
> 
> (1) Same problem as qmp-events.txt under "2.5 Asynchronous events"
> { "event": json-string, "data": json-object,
>   "timestamp": { "seconds": json-number, "microseconds": json-number } }

Likewise.

> 3. qmp-commands.txt:
> There are 3 parts in qmp-commands.txt:
> Introduction, Regular Commands, Query Commands.
> 
> But there are some regular commands were added under "3. Query
> Commands", which is a little confused for the reader.
> e.g. blockdev-add, chardev-remove, chardev-add

Messed up upstream.  If you think it's worth fixing, please file a bug
against RHEL-7 qemu-kvm-rhev, and we'll take it from there.

(In reply to Markus Armbruster from comment #6)
> Thanks for reviewing actual contents, not just presence of the
> documentation files.
> 
> Since this bug is about their presence, I suggest to let it pass QA,
> and file separate bug(s) for contents problems worth addressing (if
> any).

Ok, agree with you.

> > (2) About the event, the format should be like:
> > { "timestamp": { "seconds": json-number, "microseconds": json-number }, "event": json-string, "data": json-object, }
> > 
> > instead of
> > 
> > { "event": json-string, "data": json-object,
> >   "timestamp": { "seconds": json-number, "microseconds": json-number } }
> 
> Both forms are equivalent, as the order of members in a JSON object
> does not matter.  Any particular reason for wanting another order
> here?
 
Yes, both forms are equivalent.
I just follow the output of the actual result, it's not a big deal actually.


> > 3. qmp-commands.txt:
> > There are 3 parts in qmp-commands.txt:
> > Introduction, Regular Commands, Query Commands.
> > 
> > But there are some regular commands were added under "3. Query
> > Commands", which is a little confused for the reader.
> > e.g. blockdev-add, chardev-remove, chardev-add
> 
> Messed up upstream.  If you think it's worth fixing, please file a bug
> against RHEL-7 qemu-kvm-rhev, and we'll take it from there.


Hi Markus,

Thanks for your explanation.

I think there are no more problems from my side, we can set this bug to 'QA' now.

Thanks.

Reproduce this bug on qemu-kvm-1.5.3-86.el7

Steps:

# ls /usr/share/doc/qemu-kvm/*qmp*
/usr/share/doc/qemu-kvm/qmp-commands.txt

Verify this bug on qemu-kvm-1.5.3-92.el7

# ls /usr/share/doc/qemu-kvm/*qmp*
/usr/share/doc/qemu-kvm/qmp-commands.txt  /usr/share/doc/qemu-kvm/qmp-events.txt  /usr/share/doc/qemu-kvm/qmp-spec.txt

This bug has been fixed.

Since the problem described in this bug report should be
resolved in a recent advisory, it has been closed with a
resolution of ERRATA.

For information on the advisory, and where to find the updated
files, follow the link below.

If the solution does not work for you, open a new bug report.

https://rhn.redhat.com/errata/RHBA-2015-2213.html