[PATCH 1/9] qapi: New special feature flag "unstable"
Markus Armbruster
armbru at redhat.com
Thu Oct 28 08:36:42 UTC 2021
Kevin Wolf <kwolf at redhat.com> writes:
> Am 26.10.2021 um 11:37 hat Markus Armbruster geschrieben:
>> Kevin Wolf <kwolf at redhat.com> writes:
>>
>> > Am 25.10.2021 um 07:25 hat Markus Armbruster geschrieben:
>> >> By convention, names starting with "x-" are experimental. The parts
>> >> of external interfaces so named may be withdrawn or changed
>> >> incompatibly in future releases.
>> >>
>> >> Drawback: promoting something from experimental to stable involves a
>> >> name change. Client code needs to be updated.
>> >>
>> >> Moreover, the convention is not universally observed:
>> >>
>> >> * QOM type "input-barrier" has properties "x-origin", "y-origin".
>> >> Looks accidental, but it's ABI since 4.2.
>> >>
>> >> * QOM types "memory-backend-file", "memory-backend-memfd",
>> >> "memory-backend-ram", and "memory-backend-epc" have a property
>> >> "x-use-canonical-path-for-ramblock-id" that is documented to be
>> >> stable despite its name.
>> >>
>> >> We could document these exceptions, but documentation helps only
>> >> humans. We want to recognize "unstable" in code, like "deprecated".
>> >>
>> >> Replace the convention by a new special feature flag "unstable". It
>> >> will be recognized by the QAPI generator, like the existing feature
>> >> flag "deprecated", and unlike regular feature flags.
>> >>
>> >> This commit updates documentation and prepares tests. The next commit
>> >> updates the QAPI schema. The remaining patches update the QAPI
>> >> generator and wire up -compat policy checking.
>> >>
>> >> Signed-off-by: Markus Armbruster <armbru at redhat.com>
>> >
>> > Obviously, replacing the old convention gets rid of the old drawbacks,
>> > but adds a new one: While using x- makes it very obvious for a human
>> > user that this is an unstable feature, a feature flag in the schema will
>> > almost certainly go unnoticed in manual use.
>>
>> I thought about this, but neglected to put it in writing. My bad.
>>
>> Manual use of unstable interfaces is mostly fine. Human users can adapt
>> to changing interfaces. HMP works that way.
>>
>> Management applications are better off with a feature flag than with a
>> naming convention we sometimes ignore.
>>
>> The most potential for trouble is in between: programs that aren't
>> full-fledged management applications.
>>
>> If we want to keep "unstable" obvious to the humans who write such
>> programs, we can continue to require "x-", in addition to the feature
>> flag. We pay for it with renames, and the risk of forgetting to rename
>> in time (which is what got us the awkward stable
>> "x-use-canonical-path-for-ramblock-id"). Tradeoff. I chose not to, but
>> if y'all think we should...
>
> Just to clarify, I'm not implying that we should keep it. I'm merely
> pointing out that there is a tradeoff that requires us to make a choice.
> The decision for one of the options should be explicit rather than just
> happening as a side effect. Documenting that it was a conscious decision
> is probably best done by adding the reasoning for it to the commit
> message.
I rewrote the commit message for v2.
Thanks!
[...]
More information about the libvir-list
mailing list