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

  Adding a document describing rudimentary ABI policy and adding notice space for
any deprecation announcements

Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
CC: Thomas Monjalon <thomas.monjalon@6wind.com>
CC: "Richardson, Bruce" <bruce.richardson@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
  

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@tuxdriver.com>
> CC: Thomas Monjalon <thomas.monjalon@6wind.com>
> CC: "Richardson, Bruce" <bruce.richardson@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.
  

On Tue, Jan 20, 2015 at 08:14:50AM +0100, Thomas Monjalon wrote:
> 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@tuxdriver.com>
> > CC: Thomas Monjalon <thomas.monjalon@6wind.com>
> > CC: "Richardson, Bruce" <bruce.richardson@intel.com>

This policy looks sensible to me.
Acked-by: Bruce Richardson <bruce.richardson@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.
>
  

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Thomas Monjalon
> Sent: Tuesday, January 20, 2015 7:15 AM
> To: Neil Horman
> Cc: dev@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@tuxdriver.com>
> > CC: Thomas Monjalon <thomas.monjalon@6wind.com>
> > CC: "Richardson, Bruce" <bruce.richardson@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?

Regards,

Bernard.
  

2015-01-20 13:37, Iremonger, Bernard:
> Should there be a reference to this document in the programmers guide?

Maybe. You mean that an application developper must be aware of the deprecation
policy? So probably yes.
And I'd add that the release notes should reference the deprecations.
  

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?

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?

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?

Thanks
  

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

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Neil Horman
> Sent: Tuesday, January 20, 2015 2:24 PM
> To: Iremonger, Bernard
> Cc: dev@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@dpdk.org] On Behalf Of Thomas
> Monjalon
> > > Sent: Tuesday, January 20, 2015 7:15 AM
> > > To: Neil Horman
> > > Cc: dev@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@tuxdriver.com>
> > > > CC: Thomas Monjalon <thomas.monjalon@6wind.com>
> > > > CC: "Richardson, Bruce" <bruce.richardson@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
  

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Neil Horman
> Sent: Tuesday, January 20, 2015 2:24 PM
> To: Iremonger, Bernard
> Cc: dev@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@dpdk.org] On Behalf Of Thomas
> Monjalon
> > > Sent: Tuesday, January 20, 2015 7:15 AM
> > > To: Neil Horman
> > > Cc: dev@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@tuxdriver.com>
> > > > CC: Thomas Monjalon <thomas.monjalon@6wind.com>
> > > > CC: "Richardson, Bruce" <bruce.richardson@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?

I'd suggest that the policy itself should go in, or at least be referenced from, the programmer's guide. I agree that the deprecation notices themselves should go in the release notes.

> Neil
> 
> > Regards,
> >
> > Bernard.
> >
> >
  

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).  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.

> 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

> 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.

Thanks
Neil
  

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

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

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.

> > 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.

Thanks
  

On Tue, Jan 20, 2015 at 02:50:43PM +0000, Butler, Siobhan A wrote:
> 
> 
> > -----Original Message-----
> > From: Neil Horman [mailto:nhorman@tuxdriver.com]
> > Sent: Tuesday, January 20, 2015 2:42 PM
> > To: Butler, Siobhan A
> > Cc: Iremonger, Bernard; dev@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@dpdk.org] On Behalf Of Neil Horman
> > > > Sent: Tuesday, January 20, 2015 2:24 PM
> > > > To: Iremonger, Bernard
> > > > Cc: dev@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@dpdk.org] On Behalf Of Thomas
> > > > Monjalon
> > > > > > Sent: Tuesday, January 20, 2015 7:15 AM
> > > > > > To: Neil Horman
> > > > > > Cc: dev@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@tuxdriver.com>
> > > > > > > CC: Thomas Monjalon <thomas.monjalon@6wind.com>
> > > > > > > CC: "Richardson, Bruce" <bruce.richardson@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.
Can I infer from this then, that if I need to resend it, it would be sufficient
to simply rename this file with an .rst extension?  If so, I'm happy to do so.

> Thanks Neil - great to see more contributions to the docs coming in.
Thank you!
Neil

> S
> > 
> > > Siobhan
> > >
> 
>
  

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
>