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

[Juan Quintela <quintela@redhat.com>]

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?

Later, Juan.