Anthony asked me to take a stab at rewriting his draft to something more
along the lines of what I'm thinking. Here goes. I put some remarks
[in brackets].
FYI, I'll be out of town until Wednesday.
6. Downstream extension of QMP
------------------------------
We recommend that downstream consumers of QEMU do *not* modify QMP.
Management tools should be able to support both upstream and downstream
versions of QMP without special logic, and downstream extensions are
inherently at odds with that.
However, we recognize that it is sometimes impossible for downstreams to
avoid modifying QMP. Both upstream and downstream need to take care to
preserve long-term compatibility and interoperability.
To help with that, QMP reserves JSON object member names beginning with
'__' (double underscore) for downstream use ("downstream names"). This
means upstream will never use any downstream names for its commands,
arguments, errors, asynchronous events, and so forth.
Any new names downstream wishes to add must begin with '__'. To ensure
compatibility with other downstreams, it is strongly recommended that
you prefix the commands with '__RFQDN_' where RFQDN is a valid, reverse
fully qualified domain name which you control. For example, a qemu-kvm
specific monitor command would be:
(qemu) __org.linux-kvm_enable_irqchip
Downstream must not change the server greeting (section 2.2) other than
to offer additional capabilities. But see below for why even that is
discouraged.
Section '5 Compatibility Considerations' applies to downstream as well
as to upstream, obviously. [That section needs work!] It follows that
downstream must behave exactly like upstream for any input not
containing members with downstream names ("downstream members"), except
it may add members with downstream names to its output.
Thus, a client should not be able to distinguish downstream from
upstream as long as it doesn't send input with downstream members, and
properly ignores any downstream members in the output it receives.
[I fully support everything up to this point. I have some reservations
on the rest, and I doubt it'll be all that useful, but I don't really
mind having it, at least not in this form.]
Advice on downstream modifications:
[I made a honest effort at capturing Anthony's intentions here,
my apologies if I screwed it up.]
1. Introducing new commands is okay. If you want to extend an existing
command, consider introducing a new one with the new behaviour
instead. [FIXME Could use a rationale: why is extending bad? Make
sure to cover errors, because that's needed for 3.]
2. Introducing new asynchronous messages is okay. If you want to extend
an existing message, consider adding a new one instead. [FIXME Could
use a rationale: why is extending bad?]
3. Introducing new errors for use in new commands is okay. Adding new
errors to existing commands counts as extension, so 1. applies.
4. New capabilities are strongly discouraged. Capabilities are for
evolving the basic protocol, and multiple diverging basic protocol
dialects are most undesirable.