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
