From 22545454b67b8e243849fb586e5097f397f30e1e Mon Sep 17 00:00:00 2001 From: Ray Kinsella Date: Wed, 4 Aug 2021 10:34:31 +0100 Subject: [PATCH] doc: add policy for promotion of experimental API 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 amendment indicates that these APIs should be promoted or removed, or should at least form a conversation between the maintainer and original contributor. Signed-off-by: Ray Kinsella Acked-by: Tyler Retzlaff Acked-by: Thomas Monjalon --- doc/guides/contributing/abi_policy.rst | 28 +++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst index 4ad87dbfed..64919b6a2b 100644 --- a/doc/guides/contributing/abi_policy.rst +++ b/doc/guides/contributing/abi_policy.rst @@ -26,9 +26,11 @@ General Guidelines symbols is managed with :ref:`ABI Versioning `. #. The removal of symbols is considered an :ref:`ABI breakage `, once approved these will form part of the next ABI version. -#. Libraries or APIs marked as :ref:`experimental ` 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 ` + may be changed or removed without prior notice, + as they are not considered part of an ABI version. + The :ref:`experimental ` status of an API + is not an indefinite state. #. Updates to the :ref:`minimum hardware requirements `, which drop support for hardware which was previously supported, should be treated as an ABI change. @@ -358,3 +360,23 @@ 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 +~~~~~~~~~~~~~~~~~~~ + +An API's ``experimental`` status should be reviewed annually, +by both the maintainer and/or the original contributor. +Ordinarily APIs marked as ``experimental`` will be promoted to the stable ABI +once a maintainer has become satisfied that the API is mature +and is unlikely to change. + +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 accumulation of abandoned symbols. + +Should an ABI change, usually due to a direct change to the API's signature, +it is reasonable for the review and expiry clocks to reset. +The promotion or removal of symbols will typically form part of a conversation +between the maintainer and the original contributor.