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

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 :) [...]