On Tue, Jan 20, 2015 at 02:29:54PM +0000, Butler, Siobhan A wrote: > > > > -----Original Message----- > > From: dev [mailto:dev-bounces at dpdk.org] On Behalf Of Neil Horman > > Sent: Tuesday, January 20, 2015 2:24 PM > > To: Iremonger, Bernard > > Cc: dev at 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 at dpdk.org] On Behalf Of Thomas > > Monjalon > > > > Sent: Tuesday, January 20, 2015 7:15 AM > > > > To: Neil Horman > > > > Cc: dev at 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 <nhorman at tuxdriver.com> > > > > > CC: Thomas Monjalon <thomas.monjalon at 6wind.com> > > > > > CC: "Richardson, Bruce" <bruce.richardson at intel.com> > > > > > > > > > > --- > > > > > 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
> Siobhan >
