d/numam-dpdk
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

doc: add policy for promotion of experimental API

Browse Source 
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 <mdr@ashroe.eu>
Acked-by: Tyler Retzlaff <roretzla@linux.microsoft.com>
Acked-by: Thomas Monjalon <thomas@monjalon.net>
This commit is contained in:
Ray Kinsella 2021-08-04 10:34:31 +01:00 committed by Thomas Monjalon
parent 5c4e0deef3
commit 22545454b6
1 changed files with 25 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
doc/guides/contributing/abi_policy.rst
View File

@ -26,9 +26,11 @@ General Guidelines
symbols is managed with :ref:`ABI Versioning <abi_versioning>`. symbols is managed with :ref:`ABI Versioning <abi_versioning>`.
#. The removal of symbols is considered an :ref:`ABI breakage <abi_breakages>`, #. The removal of symbols is considered an :ref:`ABI breakage <abi_breakages>`,
once approved these will form part of the next ABI version. once approved these will form part of the next ABI version.
#. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may #. Libraries or APIs marked as :ref:`experimental <experimental_apis>`
be changed or removed without prior notice, as they are not considered part may be changed or removed without prior notice,
of an ABI version. 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 #. Updates to the :ref:`minimum hardware requirements <hw_rqmts>`, which drop
support for hardware which was previously supported, should be treated as an support for hardware which was previously supported, should be treated as an
ABI change. ABI change.
@ -358,3 +360,23 @@ Libraries
Libraries marked as ``experimental`` are entirely not considered part of an ABI Libraries marked as ``experimental`` are entirely not considered part of an ABI
version. version.
All functions in such libraries may be changed or removed without prior notice. 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.