diff mbox series

[v3] doc: add section describing new abi versions

Message ID 1597163999-4002-1-git-send-email-mdr@ashroe.eu (mailing list archive)
State Superseded, archived
Headers show
Series [v3] doc: add section describing new abi versions | expand

Checks

Context Check Description
ci/travis-robot success Travis build: passed
ci/Intel-compilation success Compilation OK
ci/checkpatch success coding style OK

Commit Message

Kinsella, Ray Aug. 11, 2020, 4:39 p.m. UTC
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(-)

--
2.7.4

Comments

Thomas Monjalon Aug. 12, 2020, 10:40 a.m. UTC | #1
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.
Kinsella, Ray Aug. 12, 2020, 11:19 a.m. UTC | #2
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.
> 
> 
>
Thomas Monjalon Aug. 12, 2020, 12:14 p.m. UTC | #3
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 :)
diff mbox series

Patch

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