thr3ads.net - Libguestfs - [Libguestfs] [PATCH 1/9] qapi: New special feature flag "unstable" [Oct 2021]

If this information is useful, please help other people find it:
Share via:

Markus Armbruster

2021-Oct-25 05:25 UTC

[Libguestfs] [PATCH 1/9] 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.

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>
---
 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

Juan Quintela

2021-Oct-25 07:15 UTC

head link

[Libguestfs] [PATCH 1/9] qapi: New special feature flag "unstable"

Markus Armbruster <armbru at redhat.com> 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 at redhat.com>
Reviewed-by: Juan Quintela <quintela at redhat.com>

Kashyap Chamarthy

2021-Oct-25 12:05 UTC

head link

[Libguestfs] [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 at 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

John Snow

2021-Oct-25 19:01 UTC

head link

[Libguestfs] [PATCH 1/9] qapi: New special feature flag "unstable"

On Mon, Oct 25, 2021 at 1:26 AM Markus Armbruster <armbru at redhat.com>
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 at 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(-)
>
> 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 at redhat.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://listman.redhat.com/archives/libguestfs/attachments/20211025/cbd943f9/attachment.htm>

Kevin Wolf

2021-Oct-26 07:37 UTC

head link

[Libguestfs] [PATCH 1/9] qapi: New special feature flag "unstable"

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.

Kevin

Libguestfs - Oct 2021 - [PATCH 1/9] qapi: New special feature flag "unstable"

[Libguestfs] [PATCH 1/9] qapi: New special feature flag "unstable"

[Libguestfs] [PATCH 1/9] qapi: New special feature flag "unstable"

[Libguestfs] [PATCH 1/9] qapi: New special feature flag "unstable"

[Libguestfs] [PATCH 1/9] qapi: New special feature flag "unstable"

[Libguestfs] [PATCH 1/9] qapi: New special feature flag "unstable"