From: "Butler, Siobhan A" <siobhan.a.butler@intel.com>
To: Neil Horman <nhorman@tuxdriver.com>, "dev@dpdk.org" <dev@dpdk.org>
Subject: Re: [dpdk-dev] [PATCH v8 4/4] docs: Add ABI documentation
Date: Thu, 22 Jan 2015 16:46:36 +0000 [thread overview]
Message-ID: <0C5AFCA4B3408848ADF2A3073F7D8CC86D4C27A7@IRSMSX109.ger.corp.intel.com> (raw)
In-Reply-To: <1421941756-30948-4-git-send-email-nhorman@tuxdriver.com>
> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Neil Horman
> Sent: Thursday, January 22, 2015 3:49 PM
> To: dev@dpdk.org
> Subject: [dpdk-dev] [PATCH v8 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
>
> 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.
>
> v8) Add missing file index.rst which was left out of the prior commit
> ---
> doc/guides/rel_notes/abi.rst | 40
> ++++++++++++++++++++++++++++++++++++++++
> doc/guides/rel_notes/index.rst | 1 +
> 2 files 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..73d88ca
> --- /dev/null
> +++ b/doc/guides/rel_notes/abi.rst
> @@ -0,0 +1,40 @@
> +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
> +-------------------
> diff --git a/doc/guides/rel_notes/index.rst b/doc/guides/rel_notes/index.rst
> index 2724149..cf712b2 100644
> --- a/doc/guides/rel_notes/index.rst
> +++ b/doc/guides/rel_notes/index.rst
> @@ -48,4 +48,5 @@ Contents
> updating_apps
> known_issues
> resolved_issues
> + abi
> faq
> --
> 2.1.0
Acked-by: Siobhan Butler <siobhan.a.butler@intel.com>
next prev parent reply other threads:[~2015-01-22 16:46 UTC|newest]
Thread overview: 99+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-12-20 21:01 [dpdk-dev] Add DSO symbol versioning to supportbackwards compatibility Neil Horman
2014-12-20 21:01 ` [dpdk-dev] [PATCH 1/4] compat: Add infrastructure to support symbol versioning Neil Horman
2014-12-22 14:01 ` Gonzalez Monroy, Sergio
2014-12-22 16:22 ` Neil Horman
2014-12-22 16:34 ` Neil Horman
2014-12-22 17:09 ` Gonzalez Monroy, Sergio
2014-12-22 19:00 ` Neil Horman
2014-12-22 20:04 ` Neil Horman
2014-12-20 21:01 ` [dpdk-dev] [PATCH 2/4] Provide initial versioning for all DPDK libraries Neil Horman
2014-12-20 21:01 ` [dpdk-dev] [PATCH 3/4] Add library version extenstion Neil Horman
2014-12-20 21:01 ` [dpdk-dev] [PATCH 4/4] docs: Add ABI documentation Neil Horman
2014-12-22 20:24 ` [dpdk-dev] [PATCH v2 1/4] compat: Add infrastructure to support symbol versioning Neil Horman
2014-12-22 20:24 ` [dpdk-dev] [PATCH v2 2/4] Provide initial versioning for all DPDK libraries Neil Horman
2014-12-22 20:24 ` [dpdk-dev] [PATCH v2 3/4] Add library version extenstion Neil Horman
2014-12-23 13:05 ` Gonzalez Monroy, Sergio
2014-12-23 15:50 ` Neil Horman
2014-12-22 20:24 ` [dpdk-dev] [PATCH v2 4/4] docs: Add ABI documentation Neil Horman
2014-12-23 9:48 ` Iremonger, Bernard
2014-12-23 13:01 ` Neil Horman
2014-12-23 13:27 ` [dpdk-dev] [PATCH v2 1/4] compat: Add infrastructure to support symbol versioning Gonzalez Monroy, Sergio
2014-12-23 15:50 ` Neil Horman
2014-12-23 15:51 ` [dpdk-dev] [PATCH v3 " Neil Horman
2014-12-23 15:51 ` [dpdk-dev] [PATCH v3 2/4] Provide initial versioning for all DPDK libraries Neil Horman
2014-12-29 16:21 ` Sergio Gonzalez Monroy
2015-01-14 15:29 ` Thomas Monjalon
2015-01-14 16:24 ` Neil Horman
2014-12-23 15:51 ` [dpdk-dev] [PATCH v3 3/4] Add library version extenstion Neil Horman
2014-12-23 16:44 ` Gonzalez Monroy, Sergio
2014-12-23 17:08 ` Neil Horman
2014-12-29 16:23 ` Sergio Gonzalez Monroy
2015-01-14 15:48 ` Thomas Monjalon
2014-12-23 15:51 ` [dpdk-dev] [PATCH v3 4/4] docs: Add ABI documentation Neil Horman
2014-12-29 16:24 ` Sergio Gonzalez Monroy
2015-01-14 15:59 ` Thomas Monjalon
2015-01-14 20:07 ` Neil Horman
2015-01-16 13:34 ` Thomas Monjalon
2014-12-29 16:20 ` [dpdk-dev] [PATCH v3 1/4] compat: Add infrastructure to support symbol versioning Sergio Gonzalez Monroy
2015-01-14 15:25 ` Thomas Monjalon
2015-01-14 20:29 ` Neil Horman
2015-01-09 12:35 ` [dpdk-dev] Add DSO symbol versioning to supportbackwards compatibility Neil Horman
2015-01-15 19:35 ` [dpdk-dev] [PATCH v4 1/4] compat: Add infrastructure to support symbol versioning Neil Horman
2015-01-15 19:35 ` [dpdk-dev] [PATCH v4 2/4] Provide initial versioning for all DPDK libraries Neil Horman
2015-01-15 19:35 ` [dpdk-dev] [PATCH v4 3/4] Add library version extenstion Neil Horman
2015-01-15 19:35 ` [dpdk-dev] [PATCH v4 4/4] docs: Add ABI documentation Neil Horman
2015-01-30 17:13 ` [dpdk-dev] [PATCH v4 1/4] compat: Add infrastructure to support symbol versioning Gray, Mark D
2015-01-16 15:33 ` [dpdk-dev] [PATCH v5 " Neil Horman
2015-01-16 15:33 ` [dpdk-dev] [PATCH v5 2/4] Provide initial versioning for all DPDK libraries Neil Horman
2015-01-16 15:33 ` [dpdk-dev] [PATCH v5 3/4] Add library version extenstion Neil Horman
2015-01-16 15:33 ` [dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation Neil Horman
2015-01-20 7:14 ` Thomas Monjalon
2015-01-20 10:47 ` Bruce Richardson
2015-01-20 13:37 ` Iremonger, Bernard
2015-01-20 13:46 ` Thomas Monjalon
2015-01-20 14:24 ` Neil Horman
2015-01-20 14:29 ` Butler, Siobhan A
2015-01-20 14:41 ` Neil Horman
2015-01-20 14:50 ` Butler, Siobhan A
2015-01-20 15:30 ` Neil Horman
2015-01-20 14:32 ` O'driscoll, Tim
2015-01-20 14:00 ` Thomas Monjalon
2015-01-20 14:37 ` Neil Horman
2015-01-20 15:06 ` Thomas Monjalon
2015-01-20 15:35 ` Neil Horman
2015-01-20 21:17 ` [dpdk-dev] [PATCH v6 1/4] compat: Add infrastructure to support symbol versioning Neil Horman
2015-01-20 21:17 ` [dpdk-dev] [PATCH v6 2/4] Provide initial versioning for all DPDK libraries Neil Horman
2015-01-20 21:17 ` [dpdk-dev] [PATCH v6 3/4] Add library version extenstion Neil Horman
2015-01-20 21:17 ` [dpdk-dev] [PATCH v6 4/4] docs: Add ABI documentation Neil Horman
2015-01-21 10:13 ` Iremonger, Bernard
2015-01-21 10:25 ` Thomas Monjalon
2015-01-21 14:59 ` Neil Horman
2015-01-21 16:05 ` Thomas Monjalon
2015-01-21 19:43 ` Neil Horman
2015-01-21 22:24 ` Thomas Monjalon
2015-01-22 19:21 ` Neil Horman
2015-01-21 20:57 ` [dpdk-dev] [PATCH v7 01/26] version: 2.0.0-rc0 Neil Horman
2015-01-21 20:57 ` [dpdk-dev] [PATCH v7 02/26] mk: fix link to static combined library Neil Horman
2015-01-21 20:57 ` [dpdk-dev] [PATCH v7 03/26] eal: fix check for power of 2 in 0 case Neil Horman
2015-01-21 20:57 ` [dpdk-dev] [PATCH v7 04/26] ethdev: fix missing parenthesis in mac check Neil Horman
2015-01-21 20:57 ` [dpdk-dev] [PATCH v7 05/26] mem: search only dpdk hugetlbfs maps Neil Horman
2015-01-21 20:57 ` [dpdk-dev] [PATCH v7 06/26] log: remove unnecessary stubs Neil Horman
2015-01-21 20:57 ` [dpdk-dev] [PATCH v7 07/26] vfio: avoid enabling while the module is not loaded Neil Horman
2015-01-21 20:57 ` [dpdk-dev] [PATCH v7 08/26] bond: fix vlan flag interpretation Neil Horman
2015-01-21 20:57 ` [dpdk-dev] [PATCH v7 09/26] app/testpmd: remove duplicated function for list parsing Neil Horman
2015-01-21 20:57 ` [dpdk-dev] [PATCH v7 10/26] nic_uio: fix thread structure compatibility for future FreeBSD Neil Horman
2015-01-21 20:58 ` [dpdk-dev] [PATCH v7 01/26] version: 2.0.0-rc0 Neil Horman
2015-01-21 20:59 ` [dpdk-dev] [PATCH v7 1/4] compat: Add infrastructure to support symbol versioning Neil Horman
2015-01-21 20:59 ` [dpdk-dev] [PATCH v7 2/4] Provide initial versioning for all DPDK libraries Neil Horman
2015-01-21 20:59 ` [dpdk-dev] [PATCH v7 3/4] Add library version extenstion Neil Horman
2015-01-21 20:59 ` [dpdk-dev] [PATCH v7 4/4] docs: Add ABI documentation Neil Horman
2015-01-22 10:56 ` Iremonger, Bernard
2015-01-22 15:37 ` Neil Horman
2015-01-22 15:49 ` [dpdk-dev] [PATCH v8 1/4] compat: Add infrastructure to support symbol versioning Neil Horman
2015-01-22 15:49 ` [dpdk-dev] [PATCH v8 2/4] Provide initial versioning for all DPDK libraries Neil Horman
2015-01-22 15:49 ` [dpdk-dev] [PATCH v8 3/4] Add library version extenstion Neil Horman
2015-01-22 15:49 ` [dpdk-dev] [PATCH v8 4/4] docs: Add ABI documentation Neil Horman
2015-01-22 16:46 ` Butler, Siobhan A [this message]
[not found] ` <1422898822-16422-1-git-send-email-nhorman@tuxdriver.com>
[not found] ` <1422898822-16422-4-git-send-email-nhorman@tuxdriver.com>
2015-02-03 15:24 ` [dpdk-dev] [PATCH v9 " Thomas Monjalon
2015-02-03 16:01 ` [dpdk-dev] Add DSO symbol versioning to supportbackwards compatibility Thomas Monjalon
2015-02-03 20:20 ` Neil Horman
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=0C5AFCA4B3408848ADF2A3073F7D8CC86D4C27A7@IRSMSX109.ger.corp.intel.com \
--to=siobhan.a.butler@intel.com \
--cc=dev@dpdk.org \
--cc=nhorman@tuxdriver.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).