[dpdk-dev] [PATCH v1] doc: policy on promotion of experimental APIs
From: Ray Kinsella <hidden>
Date: 2021-06-29 16:01:07
Subsystem:
the rest · Maintainer:
Linus Torvalds
Clarifying the ABI policy on the promotion of experimental APIS to stable. We have a fair number of APIs that have been experimental for more than 2 years. This policy ammendment indicates that these APIs should be promoted or removed, or should at least form a conservation between the maintainer and original contributor. Signed-off-by: Ray Kinsella <redacted> --- doc/guides/contributing/abi_policy.rst | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-)
diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
index 4ad87dbfed..58bc45b8a5 100644
--- a/doc/guides/contributing/abi_policy.rst
+++ b/doc/guides/contributing/abi_policy.rst@@ -26,9 +26,10 @@ General Guidelines symbols is managed with :ref:`ABI Versioning <abi_versioning>`. #. The removal of symbols is considered an :ref:`ABI breakage <abi_breakages>`, once approved these will form part of the next ABI version. -#. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may - be changed or removed without prior notice, as they are not considered part - of an ABI version. +#. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may be + changed or removed without prior notice, as they are not considered part of + an ABI version. The :ref:`experimental <experimental_apis>` status of an API + is not an indefinite state. #. Updates to the :ref:`minimum hardware requirements <hw_rqmts>`, which drop support for hardware which was previously supported, should be treated as an ABI change.
@@ -358,3 +359,16 @@ Libraries Libraries marked as ``experimental`` are entirely not considered part of an ABI version. All functions in such libraries may be changed or removed without prior notice. + +Promotion to stable +~~~~~~~~~~~~~~~~~~~ + +Ordinarily APIs marked as ``experimental`` will be promoted to the stable API +once a maintainer and/or the original contributor is satisfied that the API is +reasonably mature. In exceptional circumstances, should an API still be +classified as ``experimental`` after two years and is without any prospect of +becoming part of the stable API. The API will then become a candidate for +removal, to avoid the acculumation of abandoned symbols. + +The promotion or removal of symbols will typically form part of a conversation +between the maintainer and the original contributor.
--
2.26.2