From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga03.intel.com (mga03.intel.com [134.134.136.65]) by dpdk.org (Postfix) with ESMTP id 6CB315A15 for ; Wed, 21 Jan 2015 11:13:53 +0100 (CET) Received: from fmsmga002.fm.intel.com ([10.253.24.26]) by orsmga103.jf.intel.com with ESMTP; 21 Jan 2015 02:09:45 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.09,440,1418112000"; d="scan'208";a="665139165" Received: from irsmsx104.ger.corp.intel.com ([163.33.3.159]) by fmsmga002.fm.intel.com with ESMTP; 21 Jan 2015 02:13:44 -0800 Received: from irsmsx108.ger.corp.intel.com ([169.254.11.64]) by IRSMSX104.ger.corp.intel.com ([169.254.5.229]) with mapi id 14.03.0195.001; Wed, 21 Jan 2015 10:13:43 +0000 From: "Iremonger, Bernard" To: Neil Horman Thread-Topic: [dpdk-dev] [PATCH v6 4/4] docs: Add ABI documentation Thread-Index: AQHQNPbF5+lfvcEZ20mIY9QbyQPTypzKWLAg Date: Wed, 21 Jan 2015 10:13:42 +0000 Message-ID: <8CEF83825BEC744B83065625E567D7C2049D943D@IRSMSX108.ger.corp.intel.com> References: <1419109299-9603-1-git-send-email-nhorman@tuxdriver.com> <1421788679-9433-1-git-send-email-nhorman@tuxdriver.com> <1421788679-9433-4-git-send-email-nhorman@tuxdriver.com> In-Reply-To: <1421788679-9433-4-git-send-email-nhorman@tuxdriver.com> Accept-Language: en-GB, en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: x-originating-ip: [163.33.239.182] 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 v6 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: Wed, 21 Jan 2015 10:13:53 -0000 > -----Original Message----- > From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Neil Horman > Sent: Tuesday, January 20, 2015 9:18 PM > To: dev@dpdk.org > Subject: [dpdk-dev] [PATCH v6 4/4] docs: Add ABI documentation >=20 > Adding a document describing rudimentary ABI policy and adding notice spa= ce for any deprecation > announcements >=20 > Signed-off-by: Neil Horman > CC: Thomas Monjalon > CC: "Richardson, Bruce" >=20 > --- > Change notes: >=20 > v5) Updated documentation to add notes from Thomas M. >=20 > 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 Hi Neil, The file doc/guides/rel_notes/index.rst should be modified to include "abi= " so that the abi.rst file is included in the release notes. >=20 > 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 > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > + 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: The #. Syntax could be used for numbered lists > + 1) At least 3 acknoweldgements of the need on the dpdk.org A blank line is needed otherwise the text will concatenate. > + 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 A blank line is needed otherwise the text will concatenate. > + 3) The LIBABIVER variable in the makefilei(s) where the ABI changes > +are incorporated must be incremented in parallel with the ABI changes > +themselves A blank line is needed otherwise the text will concatenate. > + > + 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 > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > + > -- > 2.1.0 Regards, Bernard.