[v5] doc: alias to experimental tag for stable apis

diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
index 86e7dd9..c33bff1 100644
--- a/doc/guides/contributing/abi_policy.rst
+++ b/doc/guides/contributing/abi_policy.rst
@@ -160,6 +160,11 @@  The requirements for changing the ABI are:
      ``experimental``, as described in the section on :ref:`Experimental APIs
      and Libraries <experimental_apis>`.

+   - In situations in which an ``experimental`` symbol has been stable for some
+     time. When promoting the symbol to become part of the next ABI version, the
+     maintainer may choose to provide an alias to the ``experimental`` tag, so
+     as not to break consuming applications.
+
 #. If a newly proposed API functionally replaces an existing one, when the new
    API becomes non-experimental, then the old one is marked with
    ``__rte_deprecated``.
@@ -318,6 +323,11 @@  not required. Though, an API should remain in experimental state for at least
 one release. Thereafter, the normal process of posting patch for review to
 mailing list can be followed.

+After the experimental tag has been formally removed, a tree/sub-tree maintainer
+may choose to offer an alias to the experimental tag so as not to break
+applications using the symbol. The alias is then dropped at the declaration of
+next major ABI version.
+
 Libraries
 ~~~~~~~~~

diff --git a/doc/guides/contributing/abi_versioning.rst b/doc/guides/contributing/abi_versioning.rst
index 7065979..4832e8f 100644
--- a/doc/guides/contributing/abi_versioning.rst
+++ b/doc/guides/contributing/abi_versioning.rst
@@ -156,6 +156,11 @@  The macros exported are:
   ``be`` to signal that it is being used as an implementation of a particular
   version of symbol ``b``.

+* ``VERSION_SYMBOL_EXPERIMENTAL(b, e)``: Creates a symbol version table entry
+  binding versioned symbol ``b@EXPERIMENTAL`` to the internal function ``be``.
+  The macro is used when a symbol matures to become part of the stable ABI, to
+  provide an alias to experimental for some time.
+
 .. _example_abi_macro_usage:

 Examples of ABI Macro use
@@ -361,7 +366,7 @@  and a new DPDK_21 version, used by future built applications.
 .. note::

    **Before you leave**, please take care to the review the sections on
-   :ref:`Mapping static symbols <mapping_static_symbols>`, :ref:`Enabling
+   :ref:`mapping static symbols <mapping_static_symbols>`, :ref:`enabling
    versioning macros <enabling_versioning_macros>` and :ref:`ABI deprecation
    <abi_decprecation>`.

@@ -415,6 +420,157 @@  at the start of the head of the file. This will indicate to the tool-chain to
 enable the function version macros when building. There is no corresponding
 directive required for the ``make`` build system.

+.. _aliasing_experimental_symbols:
+
+Aliasing experimental symbols
+_____________________________
+
+In situations in which an ``experimental`` symbol has been stable for some time,
+and it becomes a candidate for promotion to the stable ABI. At this time, when
+promoting the symbol, maintainer may choose to provide an alias to the
+``experimental`` symbol version, so as not to break consuming applications.
+
+The process to provide an alias to ``experimental`` is similar to that, of
+:ref:`symbol visioning <example_abi_macro_usage>` described above. Assume we
+have an experimental function ``rte_acl_create`` as follows
+
+.. code-block:: c
+
+ #include <rte_compat.h>;
+
+ /*
+  * Create an acl context object for apps to
+  * manipulate
+  */
+ __rte_experimental
+ struct rte_acl_ctx *
+ rte_acl_create(const struct rte_acl_param *param)
+ {
+ ...
+ }
+
+In the map file, experimental symbols are listed as part of the ``experimental``
+version node.
+
+.. code-block:: none
+
+   DPDK_20 {
+        global:
+        ...
+
+        local: *;
+   };
+
+   EXPERIMENTAL {
+        global:
+
+        rte_acl_create
+   };
+
+When we promote the symbol to the stable ABI, we simply strip the
+``rte_experimental`` annotation from the function and move the symbol from the
+``experimental`` node, to the node of the next major ABI version as follow.
+
+.. code-block:: c
+
+ /*
+  * Create an acl context object for apps to
+  * manipulate
+  */
+ struct rte_acl_ctx *
+ rte_acl_create(const struct rte_acl_param *param)
+ {
+        ...
+ }
+
+We then update the map file, adding the symbol ``rte_acl_create`` to the ``v21``
+version node.
+
+.. code-block:: none
+
+   DPDK_20 {
+        global:
+        ...
+
+        local: *;
+   };
+
+   DPDK_21 {
+        global:
+
+        rte_acl_create
+   } DPDK_20;
+
+
+Although there are strictly no guarantees or commitments associated with
+:ref:`experimental symbols <experimental_apis>`, a maintainer may wish to offer
+an alias to experimental. The process to add an alias to experimental, is
+similar to the symbol versioning process. Assuming we have an experimental
+symbol as before, we now add the symbol to both the ``experimental`` and ``v21``
+version nodes.
+
+.. code-block:: c
+
+ #include <rte_compat.h>;
+ #include <rte_function_versioning.h>;
+
+ /*
+  * Create an acl context object for apps to
+  * manipulate
+  */
+ struct rte_acl_ctx *
+ rte_acl_create(const struct rte_acl_param *param)
+ {
+ ...
+ }
+
+ __rte_experimental
+ struct rte_acl_ctx *
+ rte_acl_create_e(const struct rte_acl_param *param)
+ {
+    return rte_acl_create(param);
+ }
+ VERSION_SYMBOL_EXPERIMENTAL(rte_acl_create, _e);
+
+ struct rte_acl_ctx *
+ rte_acl_create_v21(const struct rte_acl_param *param)
+ {
+    return rte_acl_create(param);
+ }
+ BIND_DEFAULT_SYMBOL(rte_acl_create, _v21, 21);
+
+
+In the map file, we map the symbol to both the experimental and ``v21`` version
+nodes.
+
+.. code-block:: none
+
+   DPDK_20 {
+        global:
+        ...
+
+        local: *;
+   };
+
+   DPDK_21 {
+        global:
+
+        rte_acl_create
+   } DPDK_20;
+
+   EXPERIMENTAL {
+        global:
+
+        rte_acl_create
+   };
+
+.. note::
+
+   Please note, similar to :ref:`symbol visioning <example_abi_macro_usage>`
+   when aliasing to experimental you will also need to take care of
+   :ref:`mapping static symbols <mapping_static_symbols>`.
+
+
 .. _abi_decprecation:

 Deprecating part of a public API