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 74C2E5A70 for ; Tue, 20 Jan 2015 16:31:06 +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 1YDalg-0004hQ-4j; Tue, 20 Jan 2015 10:31:04 -0500 Date: Tue, 20 Jan 2015 10:30:59 -0500 From: Neil Horman To: "Butler, Siobhan A" Message-ID: <20150120153059.GF18449@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> <20150120142401.GA18449@hmsreliant.think-freely.org> <0C5AFCA4B3408848ADF2A3073F7D8CC86D4BF204@IRSMSX109.ger.corp.intel.com> <20150120144156.GC18449@hmsreliant.think-freely.org> <0C5AFCA4B3408848ADF2A3073F7D8CC86D4BF2B4@IRSMSX109.ger.corp.intel.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <0C5AFCA4B3408848ADF2A3073F7D8CC86D4BF2B4@IRSMSX109.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 15:31:06 -0000 On Tue, Jan 20, 2015 at 02:50:43PM +0000, Butler, Siobhan A wrote: > > > > -----Original Message----- > > From: Neil Horman [mailto:nhorman@tuxdriver.com] > > Sent: Tuesday, January 20, 2015 2:42 PM > > To: Butler, Siobhan A > > Cc: Iremonger, Bernard; dev@dpdk.org > > Subject: Re: [dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation > > > > On Tue, Jan 20, 2015 at 02:29:54PM +0000, Butler, Siobhan A wrote: > > > > > > > > > > -----Original Message----- > > > > From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Neil Horman > > > > Sent: Tuesday, January 20, 2015 2:24 PM > > > > To: Iremonger, Bernard > > > > Cc: dev@dpdk.org > > > > Subject: Re: [dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation > > > > > > > > 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. > > > > > > > > > > > > > > > > Sorry to be pedantic but would you also mind sending it as a .rst file > > > instead of .txt if you're going to send as patches to Programmer's > > > Guide anyway? :) Thanks, > > Actually I'm not sure this is a good idea. The release notes get formatted and > > review by a documentation team right? I'm not sure theres value in having a > > developer write formatted text if its just going to get reviewed and > > reformatted later, is there? > > Neil > Bernard and I are the documentation team :) we use .rst files (which are plain text files) and then sphinx to auto-generate the HTML version. > It's no big issue anyway, just if you had to resend it I thought it would be handy. Can I infer from this then, that if I need to resend it, it would be sufficient to simply rename this file with an .rst extension? If so, I'm happy to do so. > Thanks Neil - great to see more contributions to the docs coming in. Thank you! Neil > S > > > > > Siobhan > > > > >