[v6,0/4] doc: changes to abi policy introducing major abi versions

  TL;DR abbreviation:
A major ABI version that all DPDK releases during a one year period
support. ABI versioning is managed at a project-level, in place of library-level
management. ABI changes to add new features are permitted, as long as ABI
compatibility with the major ABI version is maintained.

Detail:
This patch introduces major ABI versions, supported for one year and released
aligned with the LTS release. This ABI version is then supported by all
subsequent releases within that one year period. The intention is that the one
year support period, will then be reviewed after the initial year with the
intention of lengthing the support period for the next ABI version.

ABI changes that preserve ABI compatibility with the major ABI version are
permitted in subsequent releases. ABI changes, follow similar approval rules as
before with the additional gate of now requiring technical board approval. The
merging and release of ABI breaking changes would now be pushed to the
declaration of the next major ABI version.

This change encourages developers to maintain ABI compatibility with the major
ABI version, by promoting a permissive culture around those changes that
preserve ABI compatibility. This approach begins to align DPDK with those
projects that declare major ABI versions (e.g. version 2.x, 3.x) and support
those versions for some period, typically two years or more.

To provide an example of how this might work in practice:

 * DPDK v20 is declared as the supported ABI version for one year, aligned with
   the DPDK v19.11 (LTS) release. All library sonames are updated to reflect the
   new ABI version, e.g. librte_eal.so.20, librte_acl.so.20...
 * DPDK v20.02 .. v20.08 releases are ABI compatible with the DPDK v20 ABI. ABI
   changes are permitted from DPDK v20.02 onwards, with the condition that ABI
   compatibility with DPDK v20 is preserved.
 * DPDK v21 is declared as the new supported ABI version for two years, aligned
   with the DPDK v20.11 (LTS) release. The DPDK v20 ABI is now depreciated,
   library sonames are updated to v21 and ABI compatibility breaking changes may
   be introduced.

v6
 * Added figure to abi_policy.rst, comparing and contrasting the DPDK abi and
   api. (as suggested by Aaron Conole)

v5
 * Added figure to abi_policy.rst, mapping abi versions and abi compatibility to
   DPDK releases. (as suggested by Neil Horman)

v4
 * Removed changes to stable.rst, fixed typos and clarified the ABI policy
   "warning".

v3
 * Added myself as the maintainer of the ABI policy.
 * Updated the policy and versioning guides to use the year of the LTS+1 (e.g.
   v20), as the abi major version number.

v2
 * Restructured the patch into 3 patches:
   1. Splits the original versioning document into an ABI policy document
     and ABI versioning document.
   2. Add changes to the policy document introducing major ABI versions.
   3. Fixes up the versioning document in light of major ABI versioning. 
 * Reduces the initial ABI stability from two years to one year, with a review
   after the first year.
 * Adds detail around ABI version handling for experimental libraries.
 * Adds detail around chain of responsility for removing deprecated symbols.

Ray Kinsella (4):
  doc: separate versioning.rst into version and policy
  doc: changes to abi policy introducing major abi versions
  doc: updates to versioning guide for abi versions
  doc: add maintainer for abi policy

 MAINTAINERS                                        |   4 +
 doc/guides/contributing/abi_policy.rst             | 322 +++++++++++
 doc/guides/contributing/abi_versioning.rst         | 515 ++++++++++++++++++
 .../contributing/img/abi_stability_policy.png      | Bin 0 -> 61277 bytes
 doc/guides/contributing/img/what_is_an_abi.png     | Bin 0 -> 151683 bytes
 doc/guides/contributing/index.rst                  |   3 +-
 doc/guides/contributing/patches.rst                |   6 +-
 doc/guides/contributing/stable.rst                 |  12 +-
 doc/guides/contributing/versioning.rst             | 591 ---------------------
 doc/guides/rel_notes/deprecation.rst               |   2 +-
 10 files changed, 851 insertions(+), 604 deletions(-)
 create mode 100644 doc/guides/contributing/abi_policy.rst
 create mode 100644 doc/guides/contributing/abi_versioning.rst
 create mode 100644 doc/guides/contributing/img/abi_stability_policy.png
 create mode 100644 doc/guides/contributing/img/what_is_an_abi.png
 delete mode 100644 doc/guides/contributing/versioning.rst
  

27/09/2019 18:54, Ray Kinsella:
> TL;DR abbreviation:
> A major ABI version that all DPDK releases during a one year period
> support. ABI versioning is managed at a project-level, in place of library-level
> management. ABI changes to add new features are permitted, as long as ABI
> compatibility with the major ABI version is maintained.
> 
> Detail:
> This patch introduces major ABI versions, supported for one year and released
> aligned with the LTS release. This ABI version is then supported by all
> subsequent releases within that one year period. The intention is that the one
> year support period, will then be reviewed after the initial year with the
> intention of lengthing the support period for the next ABI version.

For the record, I would prefer a v7 saying it is a fixed period of time,
being one year at first and should be longer next.
Please don't state "supported for one year", which can be understood as a general truth.

> ABI changes that preserve ABI compatibility with the major ABI version are
> permitted in subsequent releases. ABI changes, follow similar approval rules as
> before with the additional gate of now requiring technical board approval. The
> merging and release of ABI breaking changes would now be pushed to the
> declaration of the next major ABI version.
> 
> This change encourages developers to maintain ABI compatibility with the major
> ABI version, by promoting a permissive culture around those changes that
> preserve ABI compatibility. This approach begins to align DPDK with those
> projects that declare major ABI versions (e.g. version 2.x, 3.x) and support
> those versions for some period, typically two years or more.
> 
> To provide an example of how this might work in practice:
> 
>  * DPDK v20 is declared as the supported ABI version for one year, aligned with
>    the DPDK v19.11 (LTS) release. All library sonames are updated to reflect the
>    new ABI version, e.g. librte_eal.so.20, librte_acl.so.20...
>  * DPDK v20.02 .. v20.08 releases are ABI compatible with the DPDK v20 ABI. ABI
>    changes are permitted from DPDK v20.02 onwards, with the condition that ABI
>    compatibility with DPDK v20 is preserved.
>  * DPDK v21 is declared as the new supported ABI version for two years, aligned
>    with the DPDK v20.11 (LTS) release. The DPDK v20 ABI is now depreciated,
>    library sonames are updated to v21 and ABI compatibility breaking changes may
>    be introduced.

OK I agree with these explanations.
  

On 21/10/2019 10:50, Thomas Monjalon wrote:
> 27/09/2019 18:54, Ray Kinsella:
>> TL;DR abbreviation:
>> A major ABI version that all DPDK releases during a one year period
>> support. ABI versioning is managed at a project-level, in place of library-level
>> management. ABI changes to add new features are permitted, as long as ABI
>> compatibility with the major ABI version is maintained.
>>
>> Detail:
>> This patch introduces major ABI versions, supported for one year and released
>> aligned with the LTS release. This ABI version is then supported by all
>> subsequent releases within that one year period. The intention is that the one
>> year support period, will then be reviewed after the initial year with the
>> intention of lengthing the support period for the next ABI version.
> 
> For the record, I would prefer a v7 saying it is a fixed period of time,
> being one year at first and should be longer next.
> Please don't state "supported for one year", which can be understood as a general truth.

Well I was very careful to only state an _intention_ to lengthen the fix period,
I though it prudent to avoid words like "should", as nothing is known until the year is behind us. 

Where I used the word "support", I talk about "abi support".
I suggest rewording as follows:-

This patch introduces major ABI versions, released aligned with the LTS release,
maintained for one year through all subsequent releases within that one year period. 
The intention is that the one year abi support period, will then be reviewed after 
the initial year with the intention of lengthening the period for the next ABI version.

> 
>> ABI changes that preserve ABI compatibility with the major ABI version are
>> permitted in subsequent releases. ABI changes, follow similar approval rules as
>> before with the additional gate of now requiring technical board approval. The
>> merging and release of ABI breaking changes would now be pushed to the
>> declaration of the next major ABI version.
>>
>> This change encourages developers to maintain ABI compatibility with the major
>> ABI version, by promoting a permissive culture around those changes that
>> preserve ABI compatibility. This approach begins to align DPDK with those
>> projects that declare major ABI versions (e.g. version 2.x, 3.x) and support
>> those versions for some period, typically two years or more.
>>
>> To provide an example of how this might work in practice:
>>
>>  * DPDK v20 is declared as the supported ABI version for one year, aligned with
>>    the DPDK v19.11 (LTS) release. All library sonames are updated to reflect the
>>    new ABI version, e.g. librte_eal.so.20, librte_acl.so.20...
>>  * DPDK v20.02 .. v20.08 releases are ABI compatible with the DPDK v20 ABI. ABI
>>    changes are permitted from DPDK v20.02 onwards, with the condition that ABI
>>    compatibility with DPDK v20 is preserved.
>>  * DPDK v21 is declared as the new supported ABI version for two years, aligned
>>    with the DPDK v20.11 (LTS) release. The DPDK v20 ABI is now depreciated,
>>    library sonames are updated to v21 and ABI compatibility breaking changes may
>>    be introduced.
> 
> OK I agree with these explanations.
> 
>
  

21/10/2019 12:10, Ray Kinsella:
> 
> On 21/10/2019 10:50, Thomas Monjalon wrote:
> > 27/09/2019 18:54, Ray Kinsella:
> >> TL;DR abbreviation:
> >> A major ABI version that all DPDK releases during a one year period
> >> support. ABI versioning is managed at a project-level, in place of library-level
> >> management. ABI changes to add new features are permitted, as long as ABI
> >> compatibility with the major ABI version is maintained.
> >>
> >> Detail:
> >> This patch introduces major ABI versions, supported for one year and released
> >> aligned with the LTS release. This ABI version is then supported by all
> >> subsequent releases within that one year period. The intention is that the one
> >> year support period, will then be reviewed after the initial year with the
> >> intention of lengthing the support period for the next ABI version.
> > 
> > For the record, I would prefer a v7 saying it is a fixed period of time,
> > being one year at first and should be longer next.
> > Please don't state "supported for one year", which can be understood as a general truth.
> 
> Well I was very careful to only state an _intention_ to lengthen the fix period,
> I though it prudent to avoid words like "should", as nothing is known until the year is behind us. 
> 
> Where I used the word "support", I talk about "abi support".
> I suggest rewording as follows:-
> 
> This patch introduces major ABI versions, released aligned with the LTS release,
> maintained for one year through all subsequent releases within that one year period. 
> The intention is that the one year abi support period, will then be reviewed after 
> the initial year with the intention of lengthening the period for the next ABI version.

Yes, looks better.

I am going to review carefully the series.
  

On 21/10/2019 15:38, Thomas Monjalon wrote:
> 21/10/2019 12:10, Ray Kinsella:
>>
>> On 21/10/2019 10:50, Thomas Monjalon wrote:
>>> 27/09/2019 18:54, Ray Kinsella:
>>>> TL;DR abbreviation:
>>>> A major ABI version that all DPDK releases during a one year period
>>>> support. ABI versioning is managed at a project-level, in place of library-level
>>>> management. ABI changes to add new features are permitted, as long as ABI
>>>> compatibility with the major ABI version is maintained.
>>>>
>>>> Detail:
>>>> This patch introduces major ABI versions, supported for one year and released
>>>> aligned with the LTS release. This ABI version is then supported by all
>>>> subsequent releases within that one year period. The intention is that the one
>>>> year support period, will then be reviewed after the initial year with the
>>>> intention of lengthing the support period for the next ABI version.
>>>
>>> For the record, I would prefer a v7 saying it is a fixed period of time,
>>> being one year at first and should be longer next.
>>> Please don't state "supported for one year", which can be understood as a general truth.
>>
>> Well I was very careful to only state an _intention_ to lengthen the fix period,
>> I though it prudent to avoid words like "should", as nothing is known until the year is behind us. 
>>
>> Where I used the word "support", I talk about "abi support".
>> I suggest rewording as follows:-
>>
>> This patch introduces major ABI versions, released aligned with the LTS release,
>> maintained for one year through all subsequent releases within that one year period. 
>> The intention is that the one year abi support period, will then be reviewed after 
>> the initial year with the intention of lengthening the period for the next ABI version.
> 
> Yes, looks better.
> 
> I am going to review carefully the series.
> 

Ok - I will hold fire on any changes then.

Ray K