Anthony, no reply from you; did it fall through the cracks? If you're
fine with my draft, I'll turn it into a proper patch.
Markus Armbruster <arm...@redhat.com> writes:
> 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.
