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

[Markus Armbruster <armbru@redhat.com>]

Juan Quintela <quintela@redhat.com> writes:

> Markus Armbruster <armbru@redhat.com> wrote:
>> Juan Quintela <quintela@redhat.com> writes:
>>
>>> Markus Armbruster <armbru@redhat.com> wrote:
>>>> Juan Quintela <quintela@redhat.com> 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?

Let's make all of them point to blockdev-mirror with NBD.  If you think
mentioning @block-incremental & friends would be useful in some or all
places would be useful, go ahead, I don't mind.