doc: add reason for three-part ABI versioning

Clarify the reasons behind the three part version numbering scheme.
Documents the fixes made in f26c2b3.

Fixes: f26c2b39b271 ("build: fix soname info for 19.11 compatibility")
Cc: stable@dpdk.org
Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>

diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
index 05ca95980b4f928b93f8324823cb56acba3c1493..a488b53cf9c10b876bfb7181fe8b386d4c53c1f2 100644 (file)
--- a/doc/guides/contributing/abi_policy.rst
+++ b/doc/guides/contributing/abi_policy.rst
@@ -39,7 +39,8 @@ General Guidelines
    releases, over a number of release cycles. This change begins with
    maintaining ABI stability through one year of DPDK releases starting from
    DPDK 19.11. This policy will be reviewed in 2020, with intention of
-   lengthening the stability period.
+   lengthening the stability period. Additional implementation detail can be
+   found in the :ref:`release notes <20_02_abi_changes>`.
 
 What is an ABI?
 ~~~~~~~~~~~~~~~

diff --git a/doc/guides/rel_notes/release_20_02.rst b/doc/guides/rel_notes/release_20_02.rst
index 870902f0b82f030b22a488c76357f10655df3d14..40ebbfac901e54872ba6dcce0ce444b151a08d56 100644 (file)
--- a/doc/guides/rel_notes/release_20_02.rst
+++ b/doc/guides/rel_notes/release_20_02.rst
@@ -298,6 +298,8 @@ API Changes
 * No change in this release.
 
 
+.. _20_02_abi_changes:
+
 ABI Changes
 -----------
 
@@ -315,6 +317,16 @@ ABI Changes
 
 * No change, kept ABI v20. DPDK 20.02 is compatible with DPDK 19.11.
 
+* The soname for each stable ABI version should be just the ABI version major
+  number without the minor number. Unfortunately both major and minor were used
+  in the v19.11 release, causing version v20.x releases to be incompatible with
+  ABI v20.0.
+
+  The `commit f26c2b39b271 <https://git.dpdk.org/dpdk/commit/?id=f26c2b39b271>`_
+  fixed the issue by switching from 2-part to 3-part ABI version numbers so that
+  we can keep v20.0 as soname and using the final digits to identify the DPDK
+  20.x releases which are ABI compatible.
+
 
 Tested Platforms
 ----------------