X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fguides%2Fcontributing%2Fversioning.rst;h=01b36247e79c043eccef277487e514e13a29e9ec;hb=5f822962498e7bff162f3ed87e15652a5b4790b9;hp=8d0fdb777c11578d74f290d165b793e0040169bb;hpb=d6f93addff90d1044aba31475758285127ca825e;p=dpdk.git

diff --git a/doc/guides/contributing/versioning.rst b/doc/guides/contributing/versioning.rst
index 8d0fdb777c..01b36247e7 100644
--- a/doc/guides/contributing/versioning.rst
+++ b/doc/guides/contributing/versioning.rst
@@ -1,3 +1,6 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright 2018 The DPDK contributors
+
 Managing ABI updates
 ====================
 
@@ -13,7 +16,9 @@ General Guidelines
 ------------------
 
 #. Whenever possible, ABI should be preserved
-#. The libraries marked in experimental state may change without constraint.
+#. Libraries or APIs marked in ``experimental`` state may change without constraint.
+#. New APIs will be marked as ``experimental`` for at least one release to allow
+   any issues found by users of the new API to be fixed quickly
 #. The addition of symbols is generally not problematic
 #. The modification of symbols can generally be managed with versioning
 #. The removal of symbols generally is an ABI break and requires bumping of the
@@ -58,6 +63,14 @@ being provided. The requirements for doing so are:
 #. At least 3 acknowledgments of the need to do so must be made on the
    dpdk.org mailing list.
 
+   - The acknowledgment of the maintainer of the component is mandatory, or if
+     no maintainer is available for the component, the tree/sub-tree maintainer
+     for that component must acknowledge the ABI change instead.
+
+   - It is also recommended that acknowledgments from different "areas of
+     interest" be sought for each deprecation, for example: from NIC vendors,
+     CPU vendors, end-users, etc.
+
 #. The changes (including an alternative map file) must be gated with
    the ``RTE_NEXT_ABI`` option, and provided with a deprecation notice at the
    same time.
@@ -86,6 +99,37 @@ readability purposes should be avoided.
    follow the relevant deprecation policy procedures as above: 3 acks and
    announcement at least one release in advance.
 
+Experimental APIs
+~~~~~~~~~~~~~~~~~
+
+APIs marked as ``experimental`` are not considered part of the ABI and may
+change without warning at any time.  Since changes to APIs are most likely
+immediately after their introduction, as users begin to take advantage of
+those new APIs and start finding issues with them, new DPDK APIs will be
+automatically marked as ``experimental`` to allow for a period of stabilization
+before they become part of a tracked ABI.
+
+Note that marking an API as experimental is a multi step process.
+To mark an API as experimental, the symbols which are desired to be exported
+must be placed in an EXPERIMENTAL version block in the corresponding libraries'
+version map script.
+Secondly, the corresponding definitions of those exported functions, and
+their forward declarations (in the development header files), must be marked
+with the ``__rte_experimental`` tag (see ``rte_compat.h``).
+The DPDK build makefiles perform a check to ensure that the map file and the
+C code reflect the same list of symbols.
+This check can be circumvented by defining ``ALLOW_EXPERIMENTAL_API``
+during compilation in the corresponding library Makefile.
+
+In addition to tagging the code with ``__rte_experimental``,
+the doxygen markup must also contain the EXPERIMENTAL string,
+and the MAINTAINERS file should note the EXPERIMENTAL libraries.
+
+For removing the experimental tag associated with an API, deprecation notice
+is not required. Though, an API should remain in experimental state for at least
+one release. Thereafter, normal process of posting patch for review to mailing
+list can be followed.
+
 Examples of Deprecation Notices
 -------------------------------