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

[Butler, Siobhan A]

> -----Original Message-----
> From: Neil Horman [mailto:nhorman at tuxdriver.com]
> Sent: Tuesday, January 20, 2015 2:42 PM
> To: Butler, Siobhan A
> Cc: Iremonger, Bernard; dev at 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 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
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.
Thanks Neil - great to see more contributions to the docs coming in.
S
> 
> > Siobhan
> >