From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp.tuxdriver.com (charlotte.tuxdriver.com [70.61.120.58]) by dpdk.org (Postfix) with ESMTP id 0BDCB5A70 for ; Tue, 20 Jan 2015 15:24:14 +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 ) id 1YDZit-0003rN-09; Tue, 20 Jan 2015 09:24:09 -0500 Date: Tue, 20 Jan 2015 09:24:01 -0500 From: Neil Horman To: "Iremonger, Bernard" Message-ID: <20150120142401.GA18449@hmsreliant.think-freely.org> 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> <8CEF83825BEC744B83065625E567D7C2049D9017@IRSMSX108.ger.corp.intel.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <8CEF83825BEC744B83065625E567D7C2049D9017@IRSMSX108.ger.corp.intel.com> User-Agent: Mutt/1.5.23 (2014-03-12) X-Spam-Score: -2.9 (--) X-Spam-Status: No 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 14:24:14 -0000 On Tue, Jan 20, 2015 at 01:37:35PM +0000, Iremonger, Bernard wrote: > > -----Original Message----- > > From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Thomas Monjalon > > Sent: Tuesday, January 20, 2015 7:15 AM > > To: Neil Horman > > Cc: dev@dpdk.org > > Subject: Re: [dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation > > > > 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" > > > > > > --- > > > 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. > > Hi Thomas, > > Should there be a reference to this document in the programmers guide? > Thats a good question. I think, as Thomas notes, it probably should be referenced in some way. The programmers guide might be good. What might be better would be checking the deprecation notices and adding them to the release notes for any given release. Thoughts? Neil > Regards, > > Bernard. > >