Eric Blake <ebl...@redhat.com> writes: > On 10/11/2016 09:57 AM, Kevin Wolf wrote: >> Should we introduce a new, clean blockdev-stream command that fixes this >> and matches the common name pattern? Of course, block-stream vs. >> blockdev-stream could be a bit confusing, too... >> > > A new command is easy to introspect (query-commands), lets us get rid of > cruft, and makes it obvious that we support everything from the get-go. > I'm favoring that option, even if it leads to slightly confusing names > of the deprecated vs. the new command.
Let's take a step back and consider extending old commands vs. adding new commands. A new command is trivial to detect in introspection. Command extensions are not as trivial to detect in introspection. Many extensions are exposed in query-qmp-schema, but not all. Back when QMP was young, Anthony argued for always adding new commands, never extend existing ones. I opposed it, because it would lead to a confusing mess of related commands, unreadable or incomplete documentation, and abysmal test coverage. However, the other extreme is also unwise: we shouldn't shoehorn new functionality into existing commands just because we can. We should ask ourselves questions like these: * Is the extended command still a sane interface? If writing clear documentation for it is hard, it perhaps isn't. Pay special attention to failure modes. Overloaded arguments are prone to confusing errors. * How will the command's users use the extension? If it requires new code paths, a new command may be more convenient for them.
