qemu/docs/devel
Markus Armbruster a3c45b3e62 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>
2021-10-29 15:55:52 +02:00
..
atomics.rst qemu/atomic.h: rename atomic_ to qatomic_ 2020-09-23 16:07:44 +01:00
bitops.rst docs: Create bitops.rst as example of kernel-docs 2019-12-17 19:36:57 +01:00
blkdebug.txt docs/: fix some comment spelling errors 2020-09-17 20:37:13 +02:00
blkverify.txt meson: link emulators without Makefile.target 2020-08-21 06:30:40 -04:00
block-coroutine-wrapper.rst scripts: add block-coroutine-wrapper.py 2020-10-05 10:59:06 +01:00
build-system.rst configure: automatically parse command line for meson -D options 2021-10-14 09:51:06 +02:00
ci-definitions.rst.inc docs: name included files ".rst.inc" 2021-10-01 19:04:45 +02:00
ci-jobs.rst.inc docs: name included files ".rst.inc" 2021-10-01 19:04:45 +02:00
ci-runners.rst.inc docs: name included files ".rst.inc" 2021-10-01 19:04:45 +02:00
ci.rst docs: name included files ".rst.inc" 2021-10-01 19:04:45 +02:00
clocks.rst clock: Provide builtin multiplier/divider 2021-09-01 11:08:19 +01:00
code-of-conduct.rst docs: link to archived Fedora code of conduct 2021-09-13 13:56:26 +02:00
conflict-resolution.rst docs: Add a QEMU Code of Conduct and Conflict Resolution Policy document 2021-04-01 13:21:02 +02:00
control-flow-integrity.rst Fix typo in CFI build documentation 2021-05-02 17:24:50 +02:00
decodetree.rst decodetree: Extend argument set syntax to allow types 2021-05-01 11:45:35 -07:00
ebpf_rss.rst docs/devel/ebpf_rss.rst: Format literals correctly 2021-08-02 11:42:38 +01:00
fuzzing.rst fuzz: add instructions for building reproducers 2021-03-16 14:30:30 -04:00
index.rst docs: standardize directory index to --- with overline 2021-09-13 13:56:26 +02:00
kconfig.rst configure, meson: move CONFIG_IVSHMEM to meson 2021-07-06 08:33:51 +02:00
loads-stores.rst accel/tcg: Add cpu_{ld,st}*_mmu interfaces 2021-10-13 08:09:53 -07:00
lockcnt.txt docs: fix references to docs/devel/atomics.rst 2021-06-02 06:51:09 +02:00
memory.rst docs: add memory API reference 2019-12-17 19:36:58 +01:00
migration.rst docs/devel/migration.rst: Format literals correctly 2021-08-02 11:42:38 +01:00
modules.rst modules: hook up modules.h to docs build 2021-07-09 18:21:33 +02:00
multi-process.rst docs: move notes inside the body of the document 2021-10-01 19:04:45 +02:00
multi-thread-tcg.rst docs/devel: Add a single top-level header to MTTCG's doc 2021-06-25 10:05:36 +01:00
multiple-iothreads.txt block: Remove bdrv_set_aio_context() 2019-06-04 16:55:58 +02:00
qapi-code-gen.rst qapi: New special feature flag "unstable" 2021-10-29 15:55:52 +02:00
qgraph.rst docs: reorganize qgraph.rst 2021-10-01 19:04:45 +02:00
qom.rst modules: add module_obj() note to QOM docs 2021-07-09 18:20:27 +02:00
qtest.rst libqos/qgraph: format qgraph comments for sphinx documentation 2021-03-09 11:26:31 +01:00
rcu.txt Docs/RCU: Correct sample code of qatomic_rcu_set 2021-01-12 12:38:03 +01:00
replay.txt replay: document development rules 2019-08-20 17:26:21 +02:00
reset.rst docs/devel/reset.rst: add doc about Resettable interface 2020-01-30 16:02:05 +00:00
s390-dasd-ipl.rst docs: rstfy s390 dasd ipl documentation 2020-02-26 18:57:07 +01:00
secure-coding-practices.rst docs/secure-coding-practices: Describe how to use 'null-co' block driver 2021-06-02 14:29:14 +02:00
stable-process.rst docs/devel: fix stable process doc formatting 2020-01-27 12:13:09 +01:00
style.rst docs/devel: expand style section of memory management 2021-03-24 14:24:52 +00:00
tcg-icount.rst tcg: Drop gen_io_end() 2021-09-08 11:09:45 +01:00
tcg-plugins.rst docs: reorganize tcg-plugins.rst 2021-10-01 19:04:45 +02:00
tcg.rst docs/devel: Explain in more detail the TB chaining mechanisms 2021-06-13 17:42:40 -07:00
testing.rst docs: reorganize testing.rst 2021-10-01 19:04:45 +02:00
tracing.rst trace: update docs with meson build information 2021-02-01 11:23:04 +00:00
ui.rst ui: add clipboard documentation 2021-05-21 09:42:44 +02:00
vfio-migration.rst docs/devel: Add VFIO device migration documentation 2021-06-18 08:38:04 -06:00
virtio-migration.txt docs: create config/, devel/ and spin/ subdirectories 2017-06-07 18:22:03 +02:00
writing-qmp-commands.rst docs: convert writing-qmp-commands.txt to writing-qmp-commands.rst 2021-08-04 11:18:05 +02:00