From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga09.intel.com (mga09.intel.com [134.134.136.24]) by dpdk.org (Postfix) with ESMTP id 2BE815A70 for ; Tue, 20 Jan 2015 14:37:38 +0100 (CET) Received: from fmsmga001.fm.intel.com ([10.253.24.23]) by orsmga102.jf.intel.com with ESMTP; 20 Jan 2015 05:34:41 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.09,434,1418112000"; d="scan'208";a="653699874" Received: from irsmsx101.ger.corp.intel.com ([163.33.3.153]) by fmsmga001.fm.intel.com with ESMTP; 20 Jan 2015 05:37:36 -0800 Received: from irsmsx108.ger.corp.intel.com ([169.254.11.64]) by IRSMSX101.ger.corp.intel.com ([169.254.1.245]) with mapi id 14.03.0195.001; Tue, 20 Jan 2015 13:37:36 +0000 From: "Iremonger, Bernard" To: Thomas Monjalon Thread-Topic: [dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation Thread-Index: AQHQNId2qnvhQE8EH0S3U7c/WDtfLJzJAvvQ Date: Tue, 20 Jan 2015 13:37:35 +0000 Message-ID: <8CEF83825BEC744B83065625E567D7C2049D9017@IRSMSX108.ger.corp.intel.com> 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> In-Reply-To: <27877815.OT7ntq4yug@xps13> Accept-Language: en-GB, en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: x-originating-ip: [163.33.239.180] Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 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 13:37:39 -0000 > -----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 >=20 > 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 de= veloppers. This policy > would be enforced by having several Acked-by lines. >=20 >=20 > 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 chan= ge 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 shoul= d be seen as cause to alter > ABI. Hi Thomas, Should there be a reference to this document in the programmers guide? Regards, Bernard.