On Mon, Oct 25, 2021 at 1:26 AM Markus Armbruster <armbru@xxxxxxxxxx> 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.
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>
---
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(-)
diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index 4071c9074a..38f2d7aad3 100644
--- a/docs/devel/qapi-code-gen.rst
+++ b/docs/devel/qapi-code-gen.rst
@@ -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
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
-------------------------------
@@ -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
optional members.
-Any name (command, event, type, member, or enum value) beginning with
-``x-`` is marked experimental, and may be withdrawn or changed
-incompatibly in a future release.
+Names beginning with ``x-`` used to signify "experimental". This
+convention has been replaced by special feature "unstable".
Pragmas ``command-name-exceptions`` and ``member-name-exceptions`` let
you violate naming rules. Use for new code is strongly discouraged. See
diff --git a/tests/qapi-schema/qapi-schema-test.json b/tests/qapi-schema/qapi-schema-test.json
index b677ab861d..43b8697002 100644
--- a/tests/qapi-schema/qapi-schema-test.json
+++ b/tests/qapi-schema/qapi-schema-test.json
@@ -273,7 +273,7 @@
'data': { 'foo': { 'type': 'int', 'features': [ 'deprecated' ] } },
'features': [ 'feature1' ] }
{ 'struct': 'FeatureStruct2',
- 'data': { 'foo': 'int' },
+ 'data': { 'foo': { 'type': 'int', 'features': [ 'unstable' ] } },
'features': [ { 'name': 'feature1' } ] }
{ 'struct': 'FeatureStruct3',
'data': { 'foo': 'int' },
@@ -331,7 +331,7 @@
{ 'command': 'test-command-features1',
'features': [ 'deprecated' ] }
{ 'command': 'test-command-features3',
- 'features': [ 'feature1', 'feature2' ] }
+ 'features': [ 'unstable', 'feature1', 'feature2' ] }
{ 'command': 'test-command-cond-features1',
'features': [ { 'name': 'feature1', 'if': 'TEST_IF_FEATURE_1'} ] }
@@ -348,3 +348,6 @@
{ 'event': 'TEST_EVENT_FEATURES1',
'features': [ 'deprecated' ] }
+
+{ 'event': 'TEST_EVENT_FEATURES2',
+ 'features': [ 'unstable' ] }
diff --git a/tests/qapi-schema/qapi-schema-test.out b/tests/qapi-schema/qapi-schema-test.out
index 16846dbeb8..1f9585fa9b 100644
--- a/tests/qapi-schema/qapi-schema-test.out
+++ b/tests/qapi-schema/qapi-schema-test.out
@@ -308,6 +308,7 @@ object FeatureStruct1
feature feature1
object FeatureStruct2
member foo: int optional=False
+ feature unstable
feature feature1
object FeatureStruct3
member foo: int optional=False
@@ -373,6 +374,7 @@ command test-command-features1 None -> None
feature deprecated
command test-command-features3 None -> None
gen=True success_response=True boxed=False oob=False preconfig=False
+ feature unstable
feature feature1
feature feature2
command test-command-cond-features1 None -> None
@@ -394,6 +396,9 @@ event TEST_EVENT_FEATURES0 FeatureStruct1
event TEST_EVENT_FEATURES1 None
boxed=False
feature deprecated
+event TEST_EVENT_FEATURES2 None
+ boxed=False
+ feature unstable
module include/sub-module.json
include sub-sub-module.json
object SecondArrayRef
--
2.31.1
Feels odd to combine the doc update *and* test prep, but eh, whatever.
Reviewed-by: John Snow <jsnow@xxxxxxxxxx>
