[dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation

Neil Horman nhorman at tuxdriver.com
Tue Jan 20 15:41:57 CET 2015


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
> 


More information about the dev mailing list