Markus Armbruster
2021-Oct-26 15:15 UTC
[Libguestfs] [PATCH 1/9] qapi: New special feature flag "unstable"
Daniel P. Berrang? <berrange at redhat.com> writes:> On Tue, Oct 26, 2021 at 11:37:19AM +0200, Markus Armbruster wrote: >> 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. > > 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.
Daniel P. Berrangé
2021-Oct-26 15:22 UTC
[Libguestfs] [PATCH 1/9] qapi: New special feature flag "unstable"
On Tue, Oct 26, 2021 at 05:15:10PM +0200, Markus Armbruster wrote:> Daniel P. Berrang? <berrange at redhat.com> writes: > > > On Tue, Oct 26, 2021 at 11:37:19AM +0200, Markus Armbruster wrote: > >> 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. > > > > 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 :)That's from the pov of the mgmt app. I meant from the POV of QEMU maintainers forgetting to add "unstable" flag, just as they might forget to add a "x-" prefix. Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|