Daniel P. Berrangé <berrange@xxxxxxxxxx> writes: > On Tue, Oct 26, 2021 at 11:37:19AM +0200, Markus Armbruster wrote: >> Kevin Wolf <kwolf@xxxxxxxxxx> 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@xxxxxxxxxx> >> > >> > 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. > > We will sometimes ignore/forget the feature flag too though, so I'm > not convinced there's much difference there. -compat unstable-input=reject,unstable-output=hide should help you stay on the straight & narrow :) >> 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... > > IMHO the renames arguably make life easier for mgmt apps, as they > only need to check for the name without the x- prefix, and they > know they won't be accidentally using the fature from an older > QEMU where it was unstable because the older QEMU had a different > name they won't be checking for. > > We can just as easily forget to remove the "unstable" feature > flag, as forget to rename. > > The plus point about the feature flag is that it is aligned with > the "deprecated" feature flag, and potentially aligned with a > future "insecure" feature flag. Yup.
