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.