Thank you Neil for writing this document. This is a really important change in DPDK. It would be very good to have comments or acknowledgement from several developpers. This policy would be enforced by having several Acked-by lines.
2015-01-16 10:33, Neil Horman: > Adding a document describing rudimentary ABI policy and adding notice space > for > any deprecation announcements > > Signed-off-by: Neil Horman <nhorman at tuxdriver.com> > CC: Thomas Monjalon <thomas.monjalon at 6wind.com> > CC: "Richardson, Bruce" <bruce.richardson at intel.com> > > --- > Change notes: > > v5) Updated documentation to add notes from Thomas M. > --- > doc/abi.txt | 36 ++++++++++++++++++++++++++++++++++++ > 1 file changed, 36 insertions(+) > create mode 100644 doc/abi.txt > > diff --git a/doc/abi.txt b/doc/abi.txt > new file mode 100644 > index 0000000..14be464 > --- /dev/null > +++ b/doc/abi.txt > @@ -0,0 +1,36 @@ > +ABI policy: > + ABI versions are set at the time of major release labeling, and ABI may > +change multiple times between the last labeling and the HEAD label of the git > +tree without warning > + > + ABI versions, once released are available until such time as their > +deprecation has been noted here for at least one major release cycle, after > it > +has been tagged. E.g. the ABI for DPDK 1.8 is shipped, and then the > decision to > +remove it is made during the development of DPDK 1.9. The decision will be > +recorded here, shipped with the DPDK 1.9 release, and actually removed when > DPDK > +1.10 ships. > + > + ABI versions may be deprecated in whole, or in part as needed by a given > +update. > + > + Some ABI changes may be too significant to reasonably maintain multiple > +versions of. In those events ABI's may be updated without backward > +compatibility provided. The requirements for doing so are: > + 1) At least 3 acknoweldgements of the need on the dpdk.org > + 2) A full deprecation cycle must be made to offer downstream consumers > +sufficient warning of the change. E.g. if dpdk 2.0 is under development when > +the change is proposed, a deprecation notice must be added to this file, and > +released with dpdk 2.0. Then the change may be incorporated for dpdk 2.1 > + 3) The LIBABIVER variable in the makefilei(s) where the ABI changes are > +incorporated must be incremented in parallel with the ABI changes themselves > + > + Note that the above process for ABI deprecation should not be undertaken > +lightly. ABI stability is extreemely important for downstream consumers of > the > +DPDK, especially when distributed in shared object form. Every effort > should be > +made to preserve ABI whenever possible. For instance, reorganizing public > +structure field for astetic or readability purposes should be avoided as it > will > +cause ABI breakage. Only significant (e.g. performance) reasons should be > seen > +as cause to alter ABI.
