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

[Iremonger, Bernard]

> -----Original Message-----
> From: dev [mailto:dev-bounces at dpdk.org] On Behalf Of Neil Horman
> Sent: Wednesday, January 21, 2015 9:00 PM
> To: dev at dpdk.org
> Subject: [dpdk-dev] [PATCH v7 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>

Hi Neil,

Tried to apply the patch and build it, the following warnings occurred.

Applying: docs: Add ABI documentation
/nfs/sie/disks/git_workspace/bairemon/dpdk-doc-next/.git/rebase-apply/patch:55: trailing whitespace.
-------------------------------  
/nfs/sie/disks/git_workspace/bairemon/dpdk-doc-next/.git/rebase-apply/patch:22: new blank line at EOF.
+
warning: 2 lines add whitespace errors.

sivswdev01> make doc-guides-html
sphinx for guides...
/nfs/sie/disks/git_workspace/bairemon/dpdk-doc-next/doc/guides/rel_notes/abi.rst:: WARNING: document isn't included in any toctree

Change to doc/guides/rel_notes/index.rst is missing from the patch.

Suggest applying and building the patch and then checking the generated HTML in Firefox to see that it is as you expect.
file:///home/nhorman/dpdk-doc-next/build/doc/html/guides/rel_notes/index.html

Regards,

Bernard.

 
> 
> ---
> Change notes:
> 
> v5) Updated documentation to add notes from Thomas M.
> 
> v6) Moved abi.txt to guides/rel_notes/abi.rst
> 
> v7) Updated abi.rst to integrate with index file
>     Updated abi.rst to conform to rst formatting
>     Updated abi.rst to include example deprecation notices.  Its not exactly the language that Thomas
> indicated, but I think it makes the idea clear.
> ---
>  doc/guides/rel_notes/abi.rst | 41 +++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 41 insertions(+)
>  create mode 100644 doc/guides/rel_notes/abi.rst
> 
> diff --git a/doc/guides/rel_notes/abi.rst b/doc/guides/rel_notes/abi.rst new file mode 100644 index
> 0000000..9b72719
> --- /dev/null
> +++ b/doc/guides/rel_notes/abi.rst
> @@ -0,0 +1,41 @@
> +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:
> +
> +#. At least 3 acknoweldgements of the need on the dpdk.org #. 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 #. 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.
> +
> +Examples of Deprecation notices
> +-------------------------------
> +* The Macro #RTE_FOO is deprecated and will be removed with version
> +2.0, to be replaced with the inline function rte_bar()
> +* The function rte_mbuf_grok has been updated to include new parameter
> +in version 2.0.  Backwards compatibility will be maintained for this
> +function until the release of version 2.1
> +* The members struct foo have been reorganized in release 2.0.  Existing binary applications will have
> backwards compatibility in release 2.0, while newly built binaries will need to reference new structure
> variant struct foo2.  Compatibility will be removed in release 2.2, and all applications will require
> updating a rebuilding to the new structure at that time, which will be renamed to the origional struct
> foo.
> +* Significant ABI changes are planned for the librte_dostuff library.  The upcomming release 2.0 will
> not contain these changes, but release 2.1 will, and no backwards compatibility is planned due to the
> invasive nature of these changes.  Binaries using this library built prior to version 2.1 will require
> updating and recompilation.
> +
> +Deprecation Notices
> +-------------------
> +
> --
> 2.1.0