Re: [dpdk-dev] [PATCH v6 4/4] docs: Add ABI documentation

["Iremonger, Bernard" <bernard.iremonger@intel.com>]

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Neil Horman
> Sent: Tuesday, January 20, 2015 9:18 PM
> To: dev@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@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.
> 
> 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.