[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH 1/9] qapi: New special feature flag "unstable"
From: |
Kevin Wolf |
Subject: |
Re: [PATCH 1/9] qapi: New special feature flag "unstable" |
Date: |
Tue, 26 Oct 2021 13:34:33 +0200 |
Am 26.10.2021 um 11:37 hat Markus Armbruster geschrieben:
> Kevin Wolf <kwolf@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@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.
> What we can't do, at least not easily, is to use *only* the "x-"
> convention: it is not reliable. We'd have to add a way to say 'this is
> stable even though the name starts with "x-"'.
No question.
Kevin
- Re: [PATCH 1/9] qapi: New special feature flag "unstable", (continued)
Re: [PATCH 1/9] qapi: New special feature flag "unstable", John Snow, 2021/10/25
Re: [PATCH 1/9] qapi: New special feature flag "unstable", Kevin Wolf, 2021/10/26
Re: [PATCH 1/9] qapi: New special feature flag "unstable", Markus Armbruster, 2021/10/26
Re: [PATCH 1/9] qapi: New special feature flag "unstable",
Kevin Wolf <=
Re: [PATCH 1/9] qapi: New special feature flag "unstable", Markus Armbruster, 2021/10/28
Re: [PATCH 1/9] qapi: New special feature flag "unstable", Daniel P . Berrangé, 2021/10/26
Re: [PATCH 1/9] qapi: New special feature flag "unstable", Markus Armbruster, 2021/10/26
Re: [PATCH 1/9] qapi: New special feature flag "unstable", Daniel P . Berrangé, 2021/10/26
Re: [PATCH 1/9] qapi: New special feature flag "unstable", Markus Armbruster, 2021/10/27
[PATCH 9/9] qapi: Extend -compat to set policy for unstable interfaces, Markus Armbruster, 2021/10/25