[dpdk-dev] [PATCH v6 4/4] docs: Add ABI documentation
Iremonger, Bernard
bernard.iremonger at intel.com
Wed Jan 21 11:13:42 CET 2015
> -----Original Message-----
> From: dev [mailto:dev-bounces at dpdk.org] On Behalf Of Neil Horman
> Sent: Tuesday, January 20, 2015 9:18 PM
> To: dev at dpdk.org
> Subject: [dpdk-dev] [PATCH v6 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 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.
>
> v6) Moved abi.txt to guides/rel_notes/abi.rst
> ---
> doc/guides/rel_notes/abi.rst | 38 ++++++++++++++++++++++++++++++++++++++
> 1 file changed, 38 insertions(+)
> create mode 100644 doc/guides/rel_notes/abi.rst
Hi Neil,
The file doc/guides/rel_notes/index.rst should be modified to include "abi" so that the abi.rst file is included in the release notes.
>
> diff --git a/doc/guides/rel_notes/abi.rst b/doc/guides/rel_notes/abi.rst new file mode 100644 index
> 0000000..98ac19d
> --- /dev/null
> +++ b/doc/guides/rel_notes/abi.rst
> @@ -0,0 +1,38 @@
> +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:
The #. Syntax could be used for numbered lists
> + 1) At least 3 acknoweldgements of the need on the dpdk.org
A blank line is needed otherwise the text will concatenate.
> + 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
A blank line is needed otherwise the text will concatenate.
> + 3) The LIBABIVER variable in the makefilei(s) where the ABI changes
> +are incorporated must be incremented in parallel with the ABI changes
> +themselves
A blank line is needed otherwise the text will concatenate.
> +
> + 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
Regards,
Bernard.
More information about the dev
mailing list