[dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation
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
[dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation
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 -- Thomas
[dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation
> -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 +, 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 +, 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 > > > > > > CC: Thomas Monjalon > > > > > > CC: "Richardson, Bruce" > > > > > > > > > > > > --- > > > > > > 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 > > > > > > 000..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. > > >
[dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation
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. -- Thomas
[dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation
> -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 +, 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 > > > > CC: Thomas Monjalon > > > > CC: "Richardson, Bruce" > > > > > > > > --- > > > > 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 > > > > 000..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. > > > >
[dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation
> -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 +, 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 > > > > CC: Thomas Monjalon > > > > CC: "Richardson, Bruce" > > > > > > > > --- > > > > 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 > > > > 000..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
[dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation
> -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 > > CC: Thomas Monjalon > > CC: "Richardson, Bruce" > > > > --- > > 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 > > 000..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.
[dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation
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 > > CC: Thomas Monjalon > > CC: "Richardson, Bruce" This policy looks sensible to me. Acked-by: Bruce Richardson > > > > --- > > 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 000..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. >
[dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation
On Tue, Jan 20, 2015 at 02:50:43PM +, Butler, Siobhan A wrote: > > > > -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 +, 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 +, 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 > > > > > > > CC: Thomas Monjalon > > > > > > > CC: "Richardson, Bruce" > > > > > > > > > > > > > > --- > > > > > > > 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 > > > > > > > 000..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: > > > >
[dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation
On Tue, Jan 20, 2015 at 02:29:54PM +, 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 +, 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 > > > > > CC: Thomas Monjalon > > > > > CC: "Richardson, Bruce" > > > > > > > > > > --- > > > > > 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 > > > > > 000..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 > > >
[dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation
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
[dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation
On Tue, Jan 20, 2015 at 01:37:35PM +, 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 > > > CC: Thomas Monjalon > > > CC: "Richardson, Bruce" > > > > > > --- > > > 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 > > > 000..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. > >
[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 > CC: Thomas Monjalon > CC: "Richardson, Bruce" > > --- > 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 000..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.
[dpdk-dev] [PATCH 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 CC: Thomas Monjalon CC: "Richardson, Bruce" --- 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 000..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. + +Deprecation Notices: + -- 2.1.0
