From: Ray Kinsella <mdr@ashroe.eu>
To: dev@dpdk.org
Cc: ferruh.yigit@intel.com, david.marchand@redhat.com,
thomas@monjalon.net, kevin.laatz@intel.com,
bruce.richardson@intel.com, hemant.agrawal@nxp.com,
Honnappa.Nagarahalli@arm.com, Ray Kinsella <mdr@ashroe.eu>,
Neil Horman <nhorman@tuxdriver.com>,
John McNamara <john.mcnamara@intel.com>,
Marko Kovacevic <marko.kovacevic@intel.com>
Subject: [dpdk-dev] [PATCH] doc: add section describing new abi versions
Date: Tue, 11 Aug 2020 16:16:13 +0100 [thread overview]
Message-ID: <1597158977-3667-1-git-send-email-mdr@ashroe.eu> (raw)
Added a section describing new abi versions, this provides pointers to
the relevant amended rules that apply during the abi breakage window.
Also remove the large note a the head of the abi policy describing the
abi stability process that has taken place over the previous year.
Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
---
doc/guides/contributing/abi_policy.rst | 37 +++++++++++++++++++++++-------
doc/guides/contributing/abi_versioning.rst | 6 ++---
2 files changed, 32 insertions(+), 11 deletions(-)
diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
index ab9daf5..fae1eb0 100644
--- a/doc/guides/contributing/abi_policy.rst
+++ b/doc/guides/contributing/abi_policy.rst
@@ -14,8 +14,8 @@ General Guidelines
------------------
#. Major ABI versions are declared no more frequently than yearly. Compatibility
- with the major ABI version is mandatory in subsequent releases until a new
- major ABI version is declared.
+ with the major ABI version is mandatory in subsequent releases until a
+ :ref:`new major ABI version <new_abi_version>` is declared.
#. Major ABI versions are usually but not always declared aligned with a
:ref:`LTS release <stable_lts_releases>`.
#. The ABI version is managed at a project level in DPDK, and is reflected in
@@ -35,12 +35,6 @@ General Guidelines
.. note::
- In 2019, the DPDK community stated its intention to move to ABI stable
- releases, over a number of release cycles. This change begins with
- maintaining ABI stability through one year of DPDK releases starting from
- DPDK 19.11. This policy will be reviewed in 2020, with intention of
- lengthening the stability period. Additional implementation detail can be
- found in the :ref:`release notes <20_02_abi_changes>`.
Please note that this policy does not currently apply to the
:doc:`Windows build <../windows_gsg/intro>`.
@@ -288,11 +282,38 @@ added to the Release Notes:
these changes. Binaries using this library built prior to ABI version 21 will
require updating and recompilation.
+
+.. _new_abi_version:
+
+New ABI versions
+------------------
+
+A new ABI version may be declared aligned with a given release. The requirement
+to preserve compatibility with the previous major ABI version is then dropped
+for the duration of this release cycle. This is commonly known as the *ABI
+breakage window*, and some amended rules apply during this cycle:
+
+ * The requirement to preserve compatibility with the previous major ABI
+ version, as described in the section :ref:`abi_changes` does not apply.
+ * Contributors of compatibility preserving code in previous releases, are now
+ required to remove this compatibility code, as described in the section
+ :ref:`abi_changes`.
+ * Symbol versioning references to the old ABI version are updated to reference
+ the new ABI version, as described in the section
+ :ref:`deprecating_entire_abi`.
+ * Finally, the *ABI breakage window* is *not* permission to circumvent the
+ other aspects of the procedures to make ABI changes described in
+ :ref:`abi_changes`, that is, 3 ACKs of the requirement to break the ABI and
+ the observance of a deprecation notice are still considered mandatory.
+
.. _experimental_apis:
Experimental
------------
+Major ABI versions are usually but not always declared aligned with a
+:ref:`LTS release <stable_lts_releases>`.
+
APIs
~~~~
diff --git a/doc/guides/contributing/abi_versioning.rst b/doc/guides/contributing/abi_versioning.rst
index b1d09c7..3d35b1a 100644
--- a/doc/guides/contributing/abi_versioning.rst
+++ b/doc/guides/contributing/abi_versioning.rst
@@ -673,9 +673,9 @@ symbols.
-BIND_DEFAULT_SYMBOL(rte_acl_create, _v20, 20);
+BIND_DEFAULT_SYMBOL(rte_acl_create, _v21, 21);
-Lastly, any VERSION_SYMBOL macros that point to the old version node should be
-removed, taking care to keep, where need old code in place to support newer
-versions of the symbol.
+Lastly, any VERSION_SYMBOL macros that point to the old version nodes should be
+removed, taking care to preserve any code that is shared with the new version
+node.
Running the ABI Validator
--
2.7.4
next reply other threads:[~2020-08-11 15:16 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-08-11 15:16 Ray Kinsella [this message]
2020-08-11 16:36 ` Ray Kinsella
2020-08-11 16:39 ` [dpdk-dev] [PATCH v3] " Ray Kinsella
2020-08-12 10:40 ` Thomas Monjalon
2020-08-12 11:19 ` Kinsella, Ray
2020-08-12 12:14 ` Thomas Monjalon
2020-08-12 11:26 ` [dpdk-dev] [PATCH v4] " Ray Kinsella
2020-08-12 13:22 ` Thomas Monjalon
2020-08-12 13:56 ` Kinsella, Ray
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=1597158977-3667-1-git-send-email-mdr@ashroe.eu \
--to=mdr@ashroe.eu \
--cc=Honnappa.Nagarahalli@arm.com \
--cc=bruce.richardson@intel.com \
--cc=david.marchand@redhat.com \
--cc=dev@dpdk.org \
--cc=ferruh.yigit@intel.com \
--cc=hemant.agrawal@nxp.com \
--cc=john.mcnamara@intel.com \
--cc=kevin.laatz@intel.com \
--cc=marko.kovacevic@intel.com \
--cc=nhorman@tuxdriver.com \
--cc=thomas@monjalon.net \
/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).