Re: [PATCH v4 03/10] migration: migrate 'inc' command option is deprecated.

Markus Armbruster <armbru(a)redhat.com&gt; wrote: > Juan Quintela <quintela(a)redhat.com&gt; writes: > >> Markus Armbruster <armbru(a)redhat.com&gt; wrote: >>> Juan Quintela <quintela(a)redhat.com&gt; writes: >> So what I want, I want to remove -i/-b in the next version (9.0?). For >> the other, I want to remove it, but I don't care if the code is around >> in "deprecated" state for another couple of years if there are still >> people that feel that they want it. >> >> This is the reason that I put a pointer for -i/-b to >> @block/@block-incremental. They are "perfect" replacements. >> >> I can put here to use blockdev-mirror + NBD, but the replacement is not >> so direct. >> >> Does this make sense? > > I see where you're coming from. Now let's change perspective for a > minute: what's the purpose of deprecating stuff? > > We normally deprecate with intent to remove. > > We don't remove right away, because we promised to first deprecate for a > grace period, so users can adjust in an orderly manner. The deprecation > serves as signal "you need to adjust". The documentation that comes > with it should help with the adjustment. It's commonly of the form "use > $alternative instead". The alternative is often a direct replacement, > but not always. There could even be no replacement at all. We don't > promise replacements, we promise an orderly process, so users can > adjust. > > Sometimes, we don't have firm plans to remove, but are more like "maybe > remove when gets in the way". We could soften the "you need to adjust" > signal in documentation, but I doubt that's a good idea. Regardless, > the need to help users adjust remains. > > Back to your patches. There are two separate interfaces to block > migration, and both are deprecated at the end of the series: > > 1. Migration parameter @block-incremental & friends > > Not in the way, content to keep around for longer if it helps users. > > The deprecation documentation advises to use block-mirror with NBD > instead. All good. > > 2. QMP migrate parameters @inc and @blk > > Firm intent to remove as soon as the grace period expires, because > it's in the way. > > The deprecation documentation advises to use interface 1 instead. > But that's deprecated, too! > > Insufficiently careful readers will miss that the replacement is > deprecated, and just use it. Risks surprise when the replacement > goes away, too. > > More careful readers will realize that this advises to use something > we elsewhere advise not to use. Contradiction! Confusion ensues. > > On further reflection, these readers might conclude that the > *combined* advice is to use block-mirror with NBD instead. This is > correct. > > So why not tell them? > > Perhaps you'd like to give more nuanced advice, like "you should move > to block-mirror with NBD, but if that's not practical for you, you > should at least move to @block-incremental & friends, which will > likely stick around for longer." That's fine. All I'm asking for is > to not make things more confusing than they need to be :) > > [...] Telling this in deprecated.rst is enough? or you want me to put it also in the error/warn messages and qapi?