Re: [PATCH 1/9] qapi: New special feature flag "unstable"
On Mon, Oct 25, 2021 at 07:25:24AM +0200, Markus Armbruster wrote:
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.
Looks like there's another stable property with an "x-" prefix:
"x-remote-object", part of QOM type @RemoteObjectProperties.
Given the above "x-" properties are now stable, I take it that they
cannot be renamed now, as they might break any tools using them? My
guess is the tedious way is not worth it: deprecate them, and add the
non-x variants as "synonyms".
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.
FWIW, sounds good to me.
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>
---
docs/devel/qapi-code-gen.rst | 9 ++++++---
tests/qapi-schema/qapi-schema-test.json | 7 +++++--
tests/qapi-schema/qapi-schema-test.out | 5 +++++
3 files changed, 16 insertions(+), 5 deletions(-)
[...]
--
/kashyap