Kevin Wolf <kwolf(a)redhat.com> writes:
Am 26.10.2021 um 11:37 hat Markus Armbruster geschrieben:
> Kevin Wolf <kwolf(a)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(a)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!
[...]