[dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation
Butler, Siobhan A
siobhan.a.butler at intel.com
Tue Jan 20 15:29:54 CET 2015
> -----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,
Siobhan
More information about the dev
mailing list