From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: <nhorman@tuxdriver.com> Received: from smtp.tuxdriver.com (charlotte.tuxdriver.com [70.61.120.58]) by dpdk.org (Postfix) with ESMTP id 7B8635AB7 for <dev@dpdk.org>; Fri, 16 Jan 2015 16:33:44 +0100 (CET) Received: from hmsreliant.think-freely.org ([2001:470:8:a08:7aac:c0ff:fec2:933b] helo=localhost) by smtp.tuxdriver.com with esmtpsa (TLSv1:AES128-SHA:128) (Exim 4.63) (envelope-from <nhorman@tuxdriver.com>) id 1YC8u3-00088U-Bw; Fri, 16 Jan 2015 10:33:41 -0500 From: Neil Horman <nhorman@tuxdriver.com> To: dev@dpdk.org Date: Fri, 16 Jan 2015 10:33:09 -0500 Message-Id: <1421422389-5473-4-git-send-email-nhorman@tuxdriver.com> X-Mailer: git-send-email 2.1.0 In-Reply-To: <1421422389-5473-1-git-send-email-nhorman@tuxdriver.com> References: <1419109299-9603-1-git-send-email-nhorman@tuxdriver.com> <1421422389-5473-1-git-send-email-nhorman@tuxdriver.com> X-Spam-Score: -2.9 (--) X-Spam-Status: No Subject: [dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: patches and discussions about DPDK <dev.dpdk.org> List-Unsubscribe: <http://dpdk.org/ml/options/dev>, <mailto:dev-request@dpdk.org?subject=unsubscribe> List-Archive: <http://dpdk.org/ml/archives/dev/> List-Post: <mailto:dev@dpdk.org> List-Help: <mailto:dev-request@dpdk.org?subject=help> List-Subscribe: <http://dpdk.org/ml/listinfo/dev>, <mailto:dev-request@dpdk.org?subject=subscribe> X-List-Received-Date: Fri, 16 Jan 2015 15:33:45 -0000 Adding a document describing rudimentary ABI policy and adding notice space for any deprecation announcements Signed-off-by: Neil Horman <nhorman@tuxdriver.com> CC: Thomas Monjalon <thomas.monjalon@6wind.com> CC: "Richardson, Bruce" <bruce.richardson@intel.com> --- Change notes: v5) Updated documentation to add notes from Thomas M. --- doc/abi.txt | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 doc/abi.txt diff --git a/doc/abi.txt b/doc/abi.txt new file mode 100644 index 0000000..14be464 --- /dev/null +++ b/doc/abi.txt @@ -0,0 +1,36 @@ +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