From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga02.intel.com (mga02.intel.com [134.134.136.20]) by dpdk.org (Postfix) with ESMTP id 1E9831288 for ; Tue, 20 Jan 2015 11:47:30 +0100 (CET) Received: from orsmga002.jf.intel.com ([10.7.209.21]) by orsmga101.jf.intel.com with ESMTP; 20 Jan 2015 02:47:29 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.09,433,1418112000"; d="scan'208";a="672739736" Received: from bricha3-mobl3.ger.corp.intel.com ([10.243.20.28]) by orsmga002.jf.intel.com with SMTP; 20 Jan 2015 02:47:27 -0800 Received: by (sSMTP sendmail emulation); Tue, 20 Jan 2015 10:47:26 +0025 Date: Tue, 20 Jan 2015 10:47:26 +0000 From: Bruce Richardson To: Thomas Monjalon Message-ID: <20150120104726.GA6264@bricha3-MOBL3> References: <1419109299-9603-1-git-send-email-nhorman@tuxdriver.com> <1421422389-5473-1-git-send-email-nhorman@tuxdriver.com> <1421422389-5473-4-git-send-email-nhorman@tuxdriver.com> <27877815.OT7ntq4yug@xps13> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <27877815.OT7ntq4yug@xps13> Organization: Intel Shannon Ltd. User-Agent: Mutt/1.5.23 (2014-03-12) Cc: dev@dpdk.org Subject: Re: [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 List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 20 Jan 2015 10:47:31 -0000 On Tue, Jan 20, 2015 at 08:14:50AM +0100, Thomas Monjalon wrote: > Thank you Neil for writing this document. > This is a really important change in DPDK. > It would be very good to have comments or acknowledgement from several > developpers. This policy would be enforced by having several Acked-by lines. > > > 2015-01-16 10:33, Neil Horman: > > Adding a document describing rudimentary ABI policy and adding notice space for > > any deprecation announcements > > > > Signed-off-by: Neil Horman > > CC: Thomas Monjalon > > CC: "Richardson, Bruce" This policy looks sensible to me. Acked-by: Bruce Richardson > > > > --- > > 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. >