On Tue, Oct 26, 2021 at 05:15:10PM +0200, Markus Armbruster wrote:
Daniel P. Berrangé <berrange@redhat.com> writes:
On Tue, Oct 26, 2021 at 11:37:19AM +0200, Markus Armbruster wrote:
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.
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 :|