qapi: New special feature flag "unstable"

By convention, names starting with "x-" are experimental.  The parts
of external interfaces so named may be withdrawn or changed
incompatibly in future releases.

The naming convention makes unstable interfaces easy to recognize.
Promoting something from experimental to stable involves a name
change.  Client code needs to be updated.  Occasionally bothersome.

Worse, 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".

So support recognizing it the same way: introduce new special feature
flag "unstable".  It will be treated specially 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.

Management applications can then use query-qmp-schema and -compat to
manage or guard against use of unstable interfaces the same way as for
deprecated interfaces.

docs/devel/qapi-code-gen.txt no longer mandates the naming convention.
Using it anyway might help writers of programs that aren't
full-fledged management applications.  Not using it can save us
bothersome renames.  We'll see how that shakes out.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>
Reviewed-by: John Snow <jsnow@redhat.com>
Message-Id: <20211028102520.747396-2-armbru@redhat.com>
This commit is contained in:
Markus Armbruster 2021-10-28 12:25:12 +02:00
parent c52d69e7db
commit a3c45b3e62
3 changed files with 16 additions and 5 deletions

View File

@ -713,6 +713,10 @@ member as deprecated. It is not supported elsewhere so far.
Interfaces so marked may be withdrawn in future releases in accordance Interfaces so marked may be withdrawn in future releases in accordance
with QEMU's deprecation policy. with QEMU's deprecation policy.
Feature "unstable" marks a command, event, enum value, or struct
member as unstable. It is not supported elsewhere so far. Interfaces
so marked may be withdrawn or changed incompatibly in future releases.
Naming rules and reserved names Naming rules and reserved names
------------------------------- -------------------------------
@ -746,9 +750,8 @@ Member name ``u`` and names starting with ``has-`` or ``has_`` are reserved
for the generator, which uses them for unions and for tracking for the generator, which uses them for unions and for tracking
optional members. optional members.
Any name (command, event, type, member, or enum value) beginning with Names beginning with ``x-`` used to signify "experimental". This
``x-`` is marked experimental, and may be withdrawn or changed convention has been replaced by special feature "unstable".
incompatibly in a future release.
Pragmas ``command-name-exceptions`` and ``member-name-exceptions`` let Pragmas ``command-name-exceptions`` and ``member-name-exceptions`` let
you violate naming rules. Use for new code is strongly discouraged. See you violate naming rules. Use for new code is strongly discouraged. See

View File

@ -273,7 +273,7 @@
'data': { 'foo': { 'type': 'int', 'features': [ 'deprecated' ] } }, 'data': { 'foo': { 'type': 'int', 'features': [ 'deprecated' ] } },
'features': [ 'feature1' ] } 'features': [ 'feature1' ] }
{ 'struct': 'FeatureStruct2', { 'struct': 'FeatureStruct2',
'data': { 'foo': 'int' }, 'data': { 'foo': { 'type': 'int', 'features': [ 'unstable' ] } },
'features': [ { 'name': 'feature1' } ] } 'features': [ { 'name': 'feature1' } ] }
{ 'struct': 'FeatureStruct3', { 'struct': 'FeatureStruct3',
'data': { 'foo': 'int' }, 'data': { 'foo': 'int' },
@ -331,7 +331,7 @@
{ 'command': 'test-command-features1', { 'command': 'test-command-features1',
'features': [ 'deprecated' ] } 'features': [ 'deprecated' ] }
{ 'command': 'test-command-features3', { 'command': 'test-command-features3',
'features': [ 'feature1', 'feature2' ] } 'features': [ 'unstable', 'feature1', 'feature2' ] }
{ 'command': 'test-command-cond-features1', { 'command': 'test-command-cond-features1',
'features': [ { 'name': 'feature1', 'if': 'TEST_IF_FEATURE_1'} ] } 'features': [ { 'name': 'feature1', 'if': 'TEST_IF_FEATURE_1'} ] }
@ -348,3 +348,6 @@
{ 'event': 'TEST_EVENT_FEATURES1', { 'event': 'TEST_EVENT_FEATURES1',
'features': [ 'deprecated' ] } 'features': [ 'deprecated' ] }
{ 'event': 'TEST_EVENT_FEATURES2',
'features': [ 'unstable' ] }

View File

@ -308,6 +308,7 @@ object FeatureStruct1
feature feature1 feature feature1
object FeatureStruct2 object FeatureStruct2
member foo: int optional=False member foo: int optional=False
feature unstable
feature feature1 feature feature1
object FeatureStruct3 object FeatureStruct3
member foo: int optional=False member foo: int optional=False
@ -373,6 +374,7 @@ command test-command-features1 None -> None
feature deprecated feature deprecated
command test-command-features3 None -> None command test-command-features3 None -> None
gen=True success_response=True boxed=False oob=False preconfig=False gen=True success_response=True boxed=False oob=False preconfig=False
feature unstable
feature feature1 feature feature1
feature feature2 feature feature2
command test-command-cond-features1 None -> None command test-command-cond-features1 None -> None
@ -394,6 +396,9 @@ event TEST_EVENT_FEATURES0 FeatureStruct1
event TEST_EVENT_FEATURES1 None event TEST_EVENT_FEATURES1 None
boxed=False boxed=False
feature deprecated feature deprecated
event TEST_EVENT_FEATURES2 None
boxed=False
feature unstable
module include/sub-module.json module include/sub-module.json
include sub-sub-module.json include sub-sub-module.json
object SecondArrayRef object SecondArrayRef