[dpdk-dev] [PATCH v2] doc: policy on promotion of experimental APIs
From: Ray Kinsella <hidden>
Date: 2021-07-01 10:32:34
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> --- v2: addressing comments on abi expiry from Tyler Retzlaff. doc/guides/contributing/abi_policy.rst | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-)
diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
index 4ad87dbfed..840c295e5d 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,18 @@ 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 ABI +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. + +Should an API's Binary Interface change during the two year period, usually due +to a direct change in the to API's signature. It is reasonable for the expiry +clock to reset. The promotion or removal of symbols will typically form part of +a conversation between the maintainer and the original contributor.
--
2.26.2