DPDK patches and discussions
 help / color / mirror / Atom feed
* [dpdk-dev] [PATCH] doc: add section describing new abi versions
@ 2020-08-11 15:16 Ray Kinsella
  2020-08-11 16:36 ` Ray Kinsella
                   ` (2 more replies)
  0 siblings, 3 replies; 9+ messages in thread
From: Ray Kinsella @ 2020-08-11 15:16 UTC (permalink / raw)
  To: dev
  Cc: ferruh.yigit, david.marchand, thomas, kevin.laatz,
	bruce.richardson, hemant.agrawal, Honnappa.Nagarahalli,
	Ray Kinsella, Neil Horman, John McNamara, Marko Kovacevic

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


^ permalink raw reply	[flat|nested] 9+ messages in thread

* [dpdk-dev] [PATCH] doc: add section describing new abi versions
  2020-08-11 15:16 [dpdk-dev] [PATCH] doc: add section describing new abi versions Ray Kinsella
@ 2020-08-11 16:36 ` Ray Kinsella
  2020-08-11 16:39 ` [dpdk-dev] [PATCH v3] " Ray Kinsella
  2020-08-12 11:26 ` [dpdk-dev] [PATCH v4] " Ray Kinsella
  2 siblings, 0 replies; 9+ messages in thread
From: Ray Kinsella @ 2020-08-11 16:36 UTC (permalink / raw)
  To: dev
  Cc: ferruh.yigit, david.marchand, thomas, kevin.laatz,
	bruce.richardson, hemant.agrawal, Honnappa.Nagarahalli,
	Ray Kinsella, Neil Horman, John McNamara, Marko Kovacevic

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>
---
V2: Updated to add removing aliases to experimental.
---
 doc/guides/contributing/abi_policy.rst     | 40 ++++++++++++++++++++++++------
 doc/guides/contributing/abi_versioning.rst |  6 ++---
 2 files changed, 35 insertions(+), 11 deletions(-)

diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
index ab9daf5..31d250a 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,41 @@ 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`.
+ * Contributors of aliases to experimental in previous releases, as described in
+   section :ref:`aliasing_experimental_symbols`, are now required to remove
+   these aliases.
+ * 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

^ permalink raw reply	[flat|nested] 9+ messages in thread

* [dpdk-dev] [PATCH v3] doc: add section describing new abi versions
  2020-08-11 15:16 [dpdk-dev] [PATCH] doc: add section describing new abi versions Ray Kinsella
  2020-08-11 16:36 ` Ray Kinsella
@ 2020-08-11 16:39 ` Ray Kinsella
  2020-08-12 10:40   ` Thomas Monjalon
  2020-08-12 11:26 ` [dpdk-dev] [PATCH v4] " Ray Kinsella
  2 siblings, 1 reply; 9+ messages in thread
From: Ray Kinsella @ 2020-08-11 16:39 UTC (permalink / raw)
  To: dev
  Cc: ferruh.yigit, david.marchand, thomas, kevin.laatz,
	bruce.richardson, hemant.agrawal, Honnappa.Nagarahalli,
	Ray Kinsella, Neil Horman, John McNamara, Marko Kovacevic

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>
---
V3: Added the patch version.
V2: Updated to add removing aliases to experimental.
---
 doc/guides/contributing/abi_policy.rst     | 40 ++++++++++++++++++++++++------
 doc/guides/contributing/abi_versioning.rst |  6 ++---
 2 files changed, 35 insertions(+), 11 deletions(-)

diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
index ab9daf5..31d250a 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,41 @@ 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`.
+ * Contributors of aliases to experimental in previous releases, as described in
+   section :ref:`aliasing_experimental_symbols`, are now required to remove
+   these aliases.
+ * 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

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [dpdk-dev] [PATCH v3] doc: add section describing new abi versions
  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
  0 siblings, 1 reply; 9+ messages in thread
From: Thomas Monjalon @ 2020-08-12 10:40 UTC (permalink / raw)
  To: Ray Kinsella
  Cc: dev, ferruh.yigit, david.marchand, kevin.laatz, bruce.richardson,
	hemant.agrawal, Honnappa.Nagarahalli, Neil Horman, John McNamara,
	Marko Kovacevic

In the title and below, s/abi/ABI/

11/08/2020 18:39, Ray Kinsella:
> 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

s/a/at/

> abi stability process that has taken place over the previous year.
> 
> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
[...]
>  #. 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.

Good idea adding a link here.

[...]
> -   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>`.

OK removing past year considerations.

[...]
> +
> +.. _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.

The ending dot must be removed.

> +   :ref:`deprecating_entire_abi`.
> + * Contributors of aliases to experimental in previous releases, as described in
> +   section :ref:`aliasing_experimental_symbols`, are now required to remove
> +   these aliases.
> + * 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>`.

Why adding this sentence here?


> +
>  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);

Why updating the version here? A lot of examples are given with v20.


> -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.




^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [dpdk-dev] [PATCH v3] doc: add section describing new abi versions
  2020-08-12 10:40   ` Thomas Monjalon
@ 2020-08-12 11:19     ` Kinsella, Ray
  2020-08-12 12:14       ` Thomas Monjalon
  0 siblings, 1 reply; 9+ messages in thread
From: Kinsella, Ray @ 2020-08-12 11:19 UTC (permalink / raw)
  To: Thomas Monjalon
  Cc: dev, ferruh.yigit, david.marchand, kevin.laatz, bruce.richardson,
	hemant.agrawal, Honnappa.Nagarahalli, Neil Horman, John McNamara,
	Marko Kovacevic

v4 on the way, other notes are below. 

On 12/08/2020 11:40, Thomas Monjalon wrote:
[SNIP]

>>  Experimental
>>  ------------
>>
>> +Major ABI versions are usually but not always declared aligned with a
>> +:ref:`LTS release <stable_lts_releases>`.
> 
> Why adding this sentence here?
Will remove.

> 
> 
>> +
>>  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);
> 
> Why updating the version here? A lot of examples are given with v20.

I didn't change this then - and + are in the documentation. 

> 
> 
>> -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.
> 
> 
> 

^ permalink raw reply	[flat|nested] 9+ messages in thread

* [dpdk-dev] [PATCH v4] doc: add section describing new abi versions
  2020-08-11 15:16 [dpdk-dev] [PATCH] doc: add section describing new abi versions Ray Kinsella
  2020-08-11 16:36 ` Ray Kinsella
  2020-08-11 16:39 ` [dpdk-dev] [PATCH v3] " Ray Kinsella
@ 2020-08-12 11:26 ` Ray Kinsella
  2020-08-12 13:22   ` Thomas Monjalon
  2 siblings, 1 reply; 9+ messages in thread
From: Ray Kinsella @ 2020-08-12 11:26 UTC (permalink / raw)
  To: dev
  Cc: ferruh.yigit, david.marchand, thomas, kevin.laatz,
	bruce.richardson, hemant.agrawal, Honnappa.Nagarahalli,
	Ray Kinsella, Neil Horman, John McNamara, Marko Kovacevic

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 at 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>
---
V4: Few minor changes proposed by Thomas Monjalon.
V3: Added the patch version.
V2: Updated to add removing aliases to experimental.
---
 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..d408439 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,6 +282,33 @@ 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`.
+ * Contributors of aliases to experimental in previous releases, as described in
+   section :ref:`aliasing_experimental_symbols`, are now required to remove
+   these aliases.
+ * 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
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

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [dpdk-dev] [PATCH v3] doc: add section describing new abi versions
  2020-08-12 11:19     ` Kinsella, Ray
@ 2020-08-12 12:14       ` Thomas Monjalon
  0 siblings, 0 replies; 9+ messages in thread
From: Thomas Monjalon @ 2020-08-12 12:14 UTC (permalink / raw)
  To: Kinsella, Ray
  Cc: dev, ferruh.yigit, david.marchand, kevin.laatz, bruce.richardson,
	hemant.agrawal, Honnappa.Nagarahalli, Neil Horman, John McNamara,
	Marko Kovacevic

12/08/2020 13:19, Kinsella, Ray:
> On 12/08/2020 11:40, Thomas Monjalon wrote:
> >> --- 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);
> > 
> > Why updating the version here? A lot of examples are given with v20.
> 
> I didn't change this then - and + are in the documentation. 

Ah ah, I got trapped :)




^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [dpdk-dev] [PATCH v4] doc: add section describing new abi versions
  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
  0 siblings, 1 reply; 9+ messages in thread
From: Thomas Monjalon @ 2020-08-12 13:22 UTC (permalink / raw)
  To: Ray Kinsella
  Cc: dev, ferruh.yigit, david.marchand, kevin.laatz, bruce.richardson,
	hemant.agrawal, Honnappa.Nagarahalli, Ray Kinsella, Neil Horman,
	John McNamara, Marko Kovacevic

12/08/2020 13:26, Ray Kinsella:
> 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 at 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>

Applied, thanks

Note: I changed the position of some line breaks
to split lines at logical places in the sentences.
I think rst files would be more pleasant if arranged this way.



^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [dpdk-dev] [PATCH v4] doc: add section describing new abi versions
  2020-08-12 13:22   ` Thomas Monjalon
@ 2020-08-12 13:56     ` Kinsella, Ray
  0 siblings, 0 replies; 9+ messages in thread
From: Kinsella, Ray @ 2020-08-12 13:56 UTC (permalink / raw)
  To: Thomas Monjalon
  Cc: dev, ferruh.yigit, david.marchand, kevin.laatz, bruce.richardson,
	hemant.agrawal, Honnappa.Nagarahalli, Neil Horman, John McNamara,
	Marko Kovacevic



On 12/08/2020 14:22, Thomas Monjalon wrote:
> 12/08/2020 13:26, Ray Kinsella:
>> 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 at 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>
> 
> Applied, thanks
> 
> Note: I changed the position of some line breaks
> to split lines at logical places in the sentences.
> I think rst files would be more pleasant if arranged this way.
> 

I am a slave to emacs fill-paragraph :-)

Ray K
 

^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2020-08-12 13:56 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-08-11 15:16 [dpdk-dev] [PATCH] doc: add section describing new abi versions Ray Kinsella
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

DPDK patches and discussions

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://inbox.dpdk.org/dev/0 dev/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 dev dev/ https://inbox.dpdk.org/dev \
		dev@dpdk.org
	public-inbox-index dev

Example config snippet for mirrors.
Newsgroup available over NNTP:
	nntp://inbox.dpdk.org/inbox.dpdk.dev


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git