[dpdk-dev] [PATCH v6 4/4] docs: Add ABI documentation

[Neil Horman]

Adding a document describing rudimentary ABI policy and adding notice space for
any deprecation announcements

Signed-off-by: Neil Horman <nhorman at tuxdriver.com>
CC: Thomas Monjalon <thomas.monjalon at 6wind.com>
CC: "Richardson, Bruce" <bruce.richardson at intel.com>

---
Change notes:

v5) Updated documentation to add notes from Thomas M.

v6) Moved abi.txt to guides/rel_notes/abi.rst
---
 doc/guides/rel_notes/abi.rst | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)
 create mode 100644 doc/guides/rel_notes/abi.rst

diff --git a/doc/guides/rel_notes/abi.rst b/doc/guides/rel_notes/abi.rst
new file mode 100644
index 0000000..98ac19d
--- /dev/null
+++ b/doc/guides/rel_notes/abi.rst
@@ -0,0 +1,38 @@
+ABI policy
+==========
+	ABI versions are set at the time of major release labeling, and ABI may
+change multiple times between the last labeling and the HEAD label of the git
+tree without warning
+
+	ABI versions, once released are available until such time as their
+deprecation has been noted here for at least one major release cycle, after it
+has been tagged.  E.g. the ABI for DPDK 1.8 is shipped, and then the decision to
+remove it is made during the development of DPDK 1.9.  The decision will be
+recorded here, shipped with the DPDK 1.9 release, and actually removed when DPDK
+1.10 ships.
+
+	ABI versions may be deprecated in whole, or in part as needed by a given
+update.
+
+	Some ABI changes may be too significant to reasonably maintain multiple
+versions of.  In those events ABI's may be updated without backward
+compatibility provided.  The requirements for doing so are:
+	1) At least 3 acknoweldgements of the need on the dpdk.org
+	2) A full deprecation cycle must be made to offer downstream consumers
+sufficient warning of the change.  E.g. if dpdk 2.0 is under development when
+the change is proposed, a deprecation notice must be added to this file, and
+released with dpdk 2.0.  Then the change may be incorporated for dpdk 2.1
+	3) The LIBABIVER variable in the makefilei(s) where the ABI changes are
+incorporated must be incremented in parallel with the ABI changes themselves
+
+	Note that the above process for ABI deprecation should not be undertaken
+lightly.  ABI stability is extreemely important for downstream consumers of the
+DPDK, especially when distributed in shared object form.  Every effort should be
+made to preserve ABI whenever possible.  For instance, reorganizing public
+structure field for astetic or readability purposes should be avoided as it will
+cause ABI breakage.  Only significant (e.g. performance) reasons should be seen
+as cause to alter ABI.
+  
+Deprecation Notices
+===================
+
-- 
2.1.0