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

[Neil Horman]

On Tue, Jan 20, 2015 at 04:06:07PM +0100, Thomas Monjalon wrote:
> 2015-01-20 09:37, Neil Horman:
> > On Tue, Jan 20, 2015 at 03:00:01PM +0100, Thomas Monjalon wrote:
> > > 2015-01-16 10:33, Neil Horman:
> > > > --- /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
> > > 
> > > astetic? typo?
> > > 
> > > > +cause ABI breakage.  Only significant (e.g. performance) reasons should be seen
> > > > +as cause to alter ABI.
> > > > +  
> > > > +Deprecation Notices:
> > > 
> > > Neil, are you sure it's a good idea to put deprecations notices here instead
> > > of release notes?
> > > 
> > Funny, I just made mention of that in my last note.  I do think that the release
> > notes is the right place to "officially" announce deprecation warnings, but I
> > think we need a way for developers to communicate that efficiently (given that
> > the release notes aren't stored in the git tree).
> 
> Yes, they are:
> 	http://dpdk.org/browse/dpdk/tree/doc/guides/rel_notes
> So I suggest to remove Deprecation Notices from abi.txt and create an entry
> in release notes.
> 
> > I think this is the place for
> > developers to canonically list deprecations, and make reading this file part of
> > the release notes generation process.  That way, updates can be made as part of
> > the commit process easily.
> 
> Developpers can update the release notes themselves.
> 
ok, I was unaware. If thats the case, then yes, putting these deprecations
directly in the release notes makes the most sense. I'll resubmit with that
changed.


> > > I'm also thinking that we need to add more things in this doc:
> > > 	- case of macros/constant deprecation (API only)
> > > 	- case of structure update: must be renamed to provide ABI compatibility?
> > > 
> > I'm definately in favor of adding such notices here, but I hadn't planned for
> > any strict formatting of any given notice.  That is to say, I considered you're
> > two issues above to be able to be included here.  I have no issue with listing a
> > deprecation note that indicates macros are being removed or that sections of api
> > are being versioned to accomodate structure changes. of any sort
> 
> No, I was suggesting to explain in this doc that macro removal must be
> announced with a deprecation notice,
> and that in case structure must be reworked, the name must change if we
> want to preserve ABI compatibility with old structure.
> 
> > > Do you think we can have a tool to test the ABI compatibility by building
> > > examples/apps of previous version and checking them with built DSO of
> > > current version?
> > > 
> > I do, though I'm not sure its within the scope of this update.  The easiest way
> > to do it currently is to checkout the last released version of the dpdk, build
> > it as a DSO build, copy out one of the test/example apps, checkout the HEAD of
> > the tree, rebuild, and run the saved off test app from the first build using the
> > shared objects of the second build.  That does some rudimentary validation,
> > but it only touches on the API aspects that the application you're using makes
> > use of.  What would be better would be if we had a test application that made a
> > call to every exported API call that we have, so that we could be confident that
> > we were exhaustively testing the ABI surface.  I think thats a large piece of
> > work, but it would be beneficial to have.
> 
> Yes, it should be another patchset.
> Do you plan to work on it? It would be very convenient for developpers and
> maintainers to test ABI compatibility.
> 
Gladly, if we can get this in.  I think its an important tool.

> Thanks
> -- 
> Thomas
>