DPDK patches and discussions
 help / color / mirror / Atom feed
* [dpdk-dev] [PATCH v1] doc: policy on promotion of experimental APIs
@ 2021-06-29 16:00 Ray Kinsella
  2021-06-29 16:28 ` Tyler Retzlaff
                   ` (4 more replies)
  0 siblings, 5 replies; 20+ messages in thread
From: Ray Kinsella @ 2021-06-29 16:00 UTC (permalink / raw)
  To: dev; +Cc: ferruh.yigit, thomas, david.marchand, stephen, Ray Kinsella

Clarifying the ABI policy on the promotion of experimental APIS to stable.
We have a fair number of APIs that have been experimental for more than
2 years. This policy ammendment indicates that these APIs should be
promoted or removed, or should at least form a conservation between the
maintainer and original contributor.

Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
---
 doc/guides/contributing/abi_policy.rst | 20 +++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
index 4ad87dbfed..58bc45b8a5 100644
--- a/doc/guides/contributing/abi_policy.rst
+++ b/doc/guides/contributing/abi_policy.rst
@@ -26,9 +26,10 @@ General Guidelines
    symbols is managed with :ref:`ABI Versioning <abi_versioning>`.
 #. The removal of symbols is considered an :ref:`ABI breakage <abi_breakages>`,
    once approved these will form part of the next ABI version.
-#. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may
-   be changed or removed without prior notice, as they are not considered part
-   of an ABI version.
+#. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may be
+   changed or removed without prior notice, as they are not considered part of
+   an ABI version. The :ref:`experimental <experimental_apis>` status of an API
+   is not an indefinite state.
 #. Updates to the :ref:`minimum hardware requirements <hw_rqmts>`, which drop
    support for hardware which was previously supported, should be treated as an
    ABI change.
@@ -358,3 +359,16 @@ Libraries
 Libraries marked as ``experimental`` are entirely not considered part of an ABI
 version.
 All functions in such libraries may be changed or removed without prior notice.
+
+Promotion to stable
+~~~~~~~~~~~~~~~~~~~
+
+Ordinarily APIs marked as ``experimental`` will be promoted to the stable API
+once a maintainer and/or the original contributor is satisfied that the API is
+reasonably mature. In exceptional circumstances, should an API still be
+classified as ``experimental`` after two years and is without any prospect of
+becoming part of the stable API. The API will then become a candidate for
+removal, to avoid the acculumation of abandoned symbols.
+
+The promotion or removal of symbols will typically form part of a conversation
+between the maintainer and the original contributor.
-- 
2.26.2


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

* Re: [dpdk-dev] [PATCH v1] doc: policy on promotion of experimental APIs
  2021-06-29 16:00 [dpdk-dev] [PATCH v1] doc: policy on promotion of experimental APIs Ray Kinsella
@ 2021-06-29 16:28 ` Tyler Retzlaff
  2021-06-29 18:38   ` Kinsella, Ray
  2021-07-01 10:31 ` [dpdk-dev] [PATCH v2] " Ray Kinsella
                   ` (3 subsequent siblings)
  4 siblings, 1 reply; 20+ messages in thread
From: Tyler Retzlaff @ 2021-06-29 16:28 UTC (permalink / raw)
  To: Ray Kinsella; +Cc: dev, ferruh.yigit, thomas, david.marchand, stephen

On Tue, Jun 29, 2021 at 05:00:31PM +0100, Ray Kinsella wrote:
> Clarifying the ABI policy on the promotion of experimental APIS to stable.
> We have a fair number of APIs that have been experimental for more than
> 2 years. This policy ammendment indicates that these APIs should be
> promoted or removed, or should at least form a conservation between the
> maintainer and original contributor.
> 
> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
> ---
>  doc/guides/contributing/abi_policy.rst | 20 +++++++++++++++++---
>  1 file changed, 17 insertions(+), 3 deletions(-)
> 
> diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
> index 4ad87dbfed..58bc45b8a5 100644
> --- a/doc/guides/contributing/abi_policy.rst
> +++ b/doc/guides/contributing/abi_policy.rst
> @@ -26,9 +26,10 @@ General Guidelines
>     symbols is managed with :ref:`ABI Versioning <abi_versioning>`.
>  #. The removal of symbols is considered an :ref:`ABI breakage <abi_breakages>`,
>     once approved these will form part of the next ABI version.
> -#. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may
> -   be changed or removed without prior notice, as they are not considered part
> -   of an ABI version.
> +#. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may be
> +   changed or removed without prior notice, as they are not considered part of
> +   an ABI version. The :ref:`experimental <experimental_apis>` status of an API
> +   is not an indefinite state.
>  #. Updates to the :ref:`minimum hardware requirements <hw_rqmts>`, which drop
>     support for hardware which was previously supported, should be treated as an
>     ABI change.
> @@ -358,3 +359,16 @@ Libraries
>  Libraries marked as ``experimental`` are entirely not considered part of an ABI
>  version.
>  All functions in such libraries may be changed or removed without prior notice.
> +
> +Promotion to stable
> +~~~~~~~~~~~~~~~~~~~
> +
> +Ordinarily APIs marked as ``experimental`` will be promoted to the stable API
> +once a maintainer and/or the original contributor is satisfied that the API is
> +reasonably mature. In exceptional circumstances, should an API still be

this seems vague and arbitrary. is there a way we can have a more
quantitative metric for what "reasonably mature" means.

> +classified as ``experimental`` after two years and is without any prospect of
> +becoming part of the stable API. The API will then become a candidate for
> +removal, to avoid the acculumation of abandoned symbols.

i think with the above comment the basis for removal then depends on
whatever metric is used to determine maturity. if it is still changing
then it seems like it is useful and still evolving so perhaps should not
be removed but hasn't changed but doesn't meet the metric for being made
stable then perhaps it becomes a candidate for removal.

> +
> +The promotion or removal of symbols will typically form part of a conversation
> +between the maintainer and the original contributor.

this should extend beyond just symbols. there are other changes that
impact the abi where exported symbols don't change. e.g. additions to
return values sets.

thanks for working on this.

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

* Re: [dpdk-dev] [PATCH v1] doc: policy on promotion of experimental APIs
  2021-06-29 16:28 ` Tyler Retzlaff
@ 2021-06-29 18:38   ` Kinsella, Ray
  2021-06-30 19:56     ` Tyler Retzlaff
  0 siblings, 1 reply; 20+ messages in thread
From: Kinsella, Ray @ 2021-06-29 18:38 UTC (permalink / raw)
  To: Tyler Retzlaff; +Cc: dev, ferruh.yigit, thomas, david.marchand, stephen



On 29/06/2021 17:28, Tyler Retzlaff wrote:
> On Tue, Jun 29, 2021 at 05:00:31PM +0100, Ray Kinsella wrote:
>> Clarifying the ABI policy on the promotion of experimental APIS to stable.
>> We have a fair number of APIs that have been experimental for more than
>> 2 years. This policy ammendment indicates that these APIs should be
>> promoted or removed, or should at least form a conservation between the
>> maintainer and original contributor.
>>
>> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
>> ---
>>  doc/guides/contributing/abi_policy.rst | 20 +++++++++++++++++---
>>  1 file changed, 17 insertions(+), 3 deletions(-)
>>
>> diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
>> index 4ad87dbfed..58bc45b8a5 100644
>> --- a/doc/guides/contributing/abi_policy.rst
>> +++ b/doc/guides/contributing/abi_policy.rst
>> @@ -26,9 +26,10 @@ General Guidelines
>>     symbols is managed with :ref:`ABI Versioning <abi_versioning>`.
>>  #. The removal of symbols is considered an :ref:`ABI breakage <abi_breakages>`,
>>     once approved these will form part of the next ABI version.
>> -#. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may
>> -   be changed or removed without prior notice, as they are not considered part
>> -   of an ABI version.
>> +#. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may be
>> +   changed or removed without prior notice, as they are not considered part of
>> +   an ABI version. The :ref:`experimental <experimental_apis>` status of an API
>> +   is not an indefinite state.
>>  #. Updates to the :ref:`minimum hardware requirements <hw_rqmts>`, which drop
>>     support for hardware which was previously supported, should be treated as an
>>     ABI change.
>> @@ -358,3 +359,16 @@ Libraries
>>  Libraries marked as ``experimental`` are entirely not considered part of an ABI
>>  version.
>>  All functions in such libraries may be changed or removed without prior notice.
>> +
>> +Promotion to stable
>> +~~~~~~~~~~~~~~~~~~~
>> +
>> +Ordinarily APIs marked as ``experimental`` will be promoted to the stable API
>> +once a maintainer and/or the original contributor is satisfied that the API is
>> +reasonably mature. In exceptional circumstances, should an API still be
> 
> this seems vague and arbitrary. is there a way we can have a more
> quantitative metric for what "reasonably mature" means.
> 
>> +classified as ``experimental`` after two years and is without any prospect of
>> +becoming part of the stable API. The API will then become a candidate for
>> +removal, to avoid the acculumation of abandoned symbols.
> 
> i think with the above comment the basis for removal then depends on
> whatever metric is used to determine maturity. 
> if it is still changing
> then it seems like it is useful and still evolving so perhaps should not
> be removed but hasn't changed but doesn't meet the metric for being made
> stable then perhaps it becomes a candidate for removal.

Good idea. 

I think it is reasonable to add a clause that indicates that any change 
to the "API signature" would reset the clock.

However equally any changes to the implementation do not reset the clock.

Would that work?

> 
>> +
>> +The promotion or removal of symbols will typically form part of a conversation
>> +between the maintainer and the original contributor.
> 
> this should extend beyond just symbols. there are other changes that
> impact the abi where exported symbols don't change. e.g. additions to
> return values sets.> 
> thanks for working on this.
> 

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

* Re: [dpdk-dev] [PATCH v1] doc: policy on promotion of experimental APIs
  2021-06-29 18:38   ` Kinsella, Ray
@ 2021-06-30 19:56     ` Tyler Retzlaff
  2021-07-01  7:56       ` Ferruh Yigit
  2021-07-01 10:19       ` Kinsella, Ray
  0 siblings, 2 replies; 20+ messages in thread
From: Tyler Retzlaff @ 2021-06-30 19:56 UTC (permalink / raw)
  To: Kinsella, Ray; +Cc: dev, ferruh.yigit, thomas, david.marchand, stephen

On Tue, Jun 29, 2021 at 07:38:05PM +0100, Kinsella, Ray wrote:
> 
> 
> >> +Promotion to stable
> >> +~~~~~~~~~~~~~~~~~~~
> >> +
> >> +Ordinarily APIs marked as ``experimental`` will be promoted to the stable API
> >> +once a maintainer and/or the original contributor is satisfied that the API is
> >> +reasonably mature. In exceptional circumstances, should an API still be
> > 
> > this seems vague and arbitrary. is there a way we can have a more
> > quantitative metric for what "reasonably mature" means.
> > 
> >> +classified as ``experimental`` after two years and is without any prospect of
> >> +becoming part of the stable API. The API will then become a candidate for
> >> +removal, to avoid the acculumation of abandoned symbols.
> > 
> > i think with the above comment the basis for removal then depends on
> > whatever metric is used to determine maturity. 
> > if it is still changing
> > then it seems like it is useful and still evolving so perhaps should not
> > be removed but hasn't changed but doesn't meet the metric for being made
> > stable then perhaps it becomes a candidate for removal.
> 
> Good idea. 
> 
> I think it is reasonable to add a clause that indicates that any change 
> to the "API signature" would reset the clock.

a time based strategy works but i guess the follow-on to that is how is
the clock tracked and how does it get updated? i don't think trying to
troll through git history will be effective.

one nit, i think "api signature" doesn't cover all cases of what i would
regard as change. i would prefer to define it as "no change where api/abi
compatibility or semantic change occurred"? which is a lot more strict
but in practice is necessary to support binaries when abi/api is stable.

i.e. if a recompile is necessary with or without code change then it's a
change.

> 
> However equally any changes to the implementation do not reset the clock.
> 
> Would that work?

that works for me.

> 
> > 
> >> +
> >> +The promotion or removal of symbols will typically form part of a conversation
> >> +between the maintainer and the original contributor.
> > 
> > this should extend beyond just symbols. there are other changes that
> > impact the abi where exported symbols don't change. e.g. additions to
> > return values sets.> 
> > thanks for working on this.
> > 

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

* Re: [dpdk-dev] [PATCH v1] doc: policy on promotion of experimental APIs
  2021-06-30 19:56     ` Tyler Retzlaff
@ 2021-07-01  7:56       ` Ferruh Yigit
  2021-07-01 14:45         ` Tyler Retzlaff
  2021-07-01 10:19       ` Kinsella, Ray
  1 sibling, 1 reply; 20+ messages in thread
From: Ferruh Yigit @ 2021-07-01  7:56 UTC (permalink / raw)
  To: Tyler Retzlaff, Kinsella, Ray; +Cc: dev, thomas, david.marchand, stephen

On 6/30/2021 8:56 PM, Tyler Retzlaff wrote:
> On Tue, Jun 29, 2021 at 07:38:05PM +0100, Kinsella, Ray wrote:
>>
>>
>>>> +Promotion to stable
>>>> +~~~~~~~~~~~~~~~~~~~
>>>> +
>>>> +Ordinarily APIs marked as ``experimental`` will be promoted to the stable API
>>>> +once a maintainer and/or the original contributor is satisfied that the API is
>>>> +reasonably mature. In exceptional circumstances, should an API still be
>>>
>>> this seems vague and arbitrary. is there a way we can have a more
>>> quantitative metric for what "reasonably mature" means.
>>>
>>>> +classified as ``experimental`` after two years and is without any prospect of
>>>> +becoming part of the stable API. The API will then become a candidate for
>>>> +removal, to avoid the acculumation of abandoned symbols.
>>>
>>> i think with the above comment the basis for removal then depends on
>>> whatever metric is used to determine maturity. 
>>> if it is still changing
>>> then it seems like it is useful and still evolving so perhaps should not
>>> be removed but hasn't changed but doesn't meet the metric for being made
>>> stable then perhaps it becomes a candidate for removal.
>>
>> Good idea. 
>>
>> I think it is reasonable to add a clause that indicates that any change 
>> to the "API signature" would reset the clock.
> 
> a time based strategy works but i guess the follow-on to that is how is
> the clock tracked and how does it get updated? i don't think trying to
> troll through git history will be effective.
> 

We are grouping the new experimental APIs in the version file based on the
release they are added with a comment, thanks to Dave. Like:

        # added in 19.02
        rte_extmem_attach;
        rte_extmem_detach;
        rte_extmem_register;
        rte_extmem_unregister;

        # added in 19.05
        rte_dev_dma_map;
        rte_dev_dma_unmap;
        ....

Please check 'lib/eal/version.map' as sample.

This enables us easily see the release experimental APIs are added.

> one nit, i think "api signature" doesn't cover all cases of what i would
> regard as change. i would prefer to define it as "no change where api/abi
> compatibility or semantic change occurred"? which is a lot more strict
> but in practice is necessary to support binaries when abi/api is stable.
> 
> i.e. if a recompile is necessary with or without code change then it's a
> change.
> 
>>
>> However equally any changes to the implementation do not reset the clock.
>>
>> Would that work?
> 
> that works for me.
> 
>>
>>>
>>>> +
>>>> +The promotion or removal of symbols will typically form part of a conversation
>>>> +between the maintainer and the original contributor.
>>>
>>> this should extend beyond just symbols. there are other changes that
>>> impact the abi where exported symbols don't change. e.g. additions to
>>> return values sets.> 
>>> thanks for working on this.
>>>


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

* Re: [dpdk-dev] [PATCH v1] doc: policy on promotion of experimental APIs
  2021-06-30 19:56     ` Tyler Retzlaff
  2021-07-01  7:56       ` Ferruh Yigit
@ 2021-07-01 10:19       ` Kinsella, Ray
  2021-07-01 15:09         ` Tyler Retzlaff
  1 sibling, 1 reply; 20+ messages in thread
From: Kinsella, Ray @ 2021-07-01 10:19 UTC (permalink / raw)
  To: Tyler Retzlaff; +Cc: dev, ferruh.yigit, thomas, david.marchand, stephen



On 30/06/2021 20:56, Tyler Retzlaff wrote:
> On Tue, Jun 29, 2021 at 07:38:05PM +0100, Kinsella, Ray wrote:
>>
>>
>>>> +Promotion to stable
>>>> +~~~~~~~~~~~~~~~~~~~
>>>> +
>>>> +Ordinarily APIs marked as ``experimental`` will be promoted to the stable API
>>>> +once a maintainer and/or the original contributor is satisfied that the API is
>>>> +reasonably mature. In exceptional circumstances, should an API still be
>>>
>>> this seems vague and arbitrary. is there a way we can have a more
>>> quantitative metric for what "reasonably mature" means.
>>>
>>>> +classified as ``experimental`` after two years and is without any prospect of
>>>> +becoming part of the stable API. The API will then become a candidate for
>>>> +removal, to avoid the acculumation of abandoned symbols.
>>>
>>> i think with the above comment the basis for removal then depends on
>>> whatever metric is used to determine maturity. 
>>> if it is still changing
>>> then it seems like it is useful and still evolving so perhaps should not
>>> be removed but hasn't changed but doesn't meet the metric for being made
>>> stable then perhaps it becomes a candidate for removal.
>>
>> Good idea. 
>>
>> I think it is reasonable to add a clause that indicates that any change 
>> to the "API signature" would reset the clock.
> 
> a time based strategy works but i guess the follow-on to that is how is
> the clock tracked and how does it get updated? i don't think trying to
> troll through git history will be effective.
> 
> one nit, i think "api signature" doesn't cover all cases of what i would
> regard as change. i would prefer to define it as "no change where api/abi
> compatibility or semantic change occurred"? which is a lot more strict
> but in practice is necessary to support binaries when abi/api is stable.
> 
> i.e. if a recompile is necessary with or without code change then it's a
> change.

Having thought a bit ... this becomes a bit problematic.

Many data-structures in DPDK are nested, 
these can have a ripple effect when changed - a change to mbuf is a good example.

What I saying is ...
I don't think changes in ABI due to in-direct reasons should count.
If there is a change due to a deliberate change in the ABI signature 
that is fine, reset the clock.

If there is a change due to some nested data-structure, 
3-levels down changing in my book that doesn't count. 
As that may or may not have been deliberate, and is almost impossible to police. 

Checking anything but a deliberate change to the ABI signature,
would be practically impossible IMHO. 

> 
>>
>> However equally any changes to the implementation do not reset the clock.
>>
>> Would that work?
> 
> that works for me.

v2 on the way.

> 
>>
>>>
>>>> +
>>>> +The promotion or removal of symbols will typically form part of a conversation
>>>> +between the maintainer and the original contributor.
>>>
>>> this should extend beyond just symbols. there are other changes that
>>> impact the abi where exported symbols don't change. e.g. additions to
>>> return values sets.> 
>>> thanks for working on this.
>>>

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

* [dpdk-dev] [PATCH v2] doc: policy on promotion of experimental APIs
  2021-06-29 16:00 [dpdk-dev] [PATCH v1] doc: policy on promotion of experimental APIs Ray Kinsella
  2021-06-29 16:28 ` Tyler Retzlaff
@ 2021-07-01 10:31 ` Ray Kinsella
  2021-07-01 10:38 ` [dpdk-dev] [PATCH v3] doc: policy on the " Ray Kinsella
                   ` (2 subsequent siblings)
  4 siblings, 0 replies; 20+ messages in thread
From: Ray Kinsella @ 2021-07-01 10:31 UTC (permalink / raw)
  To: dev
  Cc: bruce.richardson, john.mcnamara, roretzla, ferruh.yigit, thomas,
	david.marchand, stephen, Ray Kinsella

Clarifying the ABI policy on the promotion of experimental APIS to stable.
We have a fair number of APIs that have been experimental for more than
2 years. This policy ammendment indicates that these APIs should be
promoted or removed, or should at least form a conservation between the
maintainer and original contributor.

Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
---
v2: addressing comments on abi expiry from Tyler Retzlaff.

 doc/guides/contributing/abi_policy.rst | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
index 4ad87dbfed..840c295e5d 100644
--- a/doc/guides/contributing/abi_policy.rst
+++ b/doc/guides/contributing/abi_policy.rst
@@ -26,9 +26,10 @@ General Guidelines
    symbols is managed with :ref:`ABI Versioning <abi_versioning>`.
 #. The removal of symbols is considered an :ref:`ABI breakage <abi_breakages>`,
    once approved these will form part of the next ABI version.
-#. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may
-   be changed or removed without prior notice, as they are not considered part
-   of an ABI version.
+#. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may be
+   changed or removed without prior notice, as they are not considered part of
+   an ABI version. The :ref:`experimental <experimental_apis>` status of an API
+   is not an indefinite state.
 #. Updates to the :ref:`minimum hardware requirements <hw_rqmts>`, which drop
    support for hardware which was previously supported, should be treated as an
    ABI change.
@@ -358,3 +359,18 @@ Libraries
 Libraries marked as ``experimental`` are entirely not considered part of an ABI
 version.
 All functions in such libraries may be changed or removed without prior notice.
+
+Promotion to stable
+~~~~~~~~~~~~~~~~~~~
+
+Ordinarily APIs marked as ``experimental`` will be promoted to the stable ABI
+once a maintainer and/or the original contributor is satisfied that the API is
+reasonably mature. In exceptional circumstances, should an API still be
+classified as ``experimental`` after two years and is without any prospect of
+becoming part of the stable API. The API will then become a candidate for
+removal, to avoid the acculumation of abandoned symbols.
+
+Should an API's Binary Interface change during the two year period, usually due
+to a direct change in the to API's signature. It is reasonable for the expiry
+clock to reset. The promotion or removal of symbols will typically form part of
+a conversation between the maintainer and the original contributor.
-- 
2.26.2


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

* [dpdk-dev] [PATCH v3] doc: policy on the promotion of experimental APIs
  2021-06-29 16:00 [dpdk-dev] [PATCH v1] doc: policy on promotion of experimental APIs Ray Kinsella
  2021-06-29 16:28 ` Tyler Retzlaff
  2021-07-01 10:31 ` [dpdk-dev] [PATCH v2] " Ray Kinsella
@ 2021-07-01 10:38 ` Ray Kinsella
  2021-07-07 18:32   ` Tyler Retzlaff
  2021-07-09  6:16   ` Jerin Jacob
  2021-08-03 16:44 ` [dpdk-dev] [PATCH v4] " Ray Kinsella
  2021-08-04  9:34 ` [dpdk-dev] [PATCH v5] " Ray Kinsella
  4 siblings, 2 replies; 20+ messages in thread
From: Ray Kinsella @ 2021-07-01 10:38 UTC (permalink / raw)
  To: dev
  Cc: bruce.richardson, john.mcnamara, roretzla, ferruh.yigit, thomas,
	david.marchand, stephen, Ray Kinsella

Clarifying the ABI policy on the promotion of experimental APIS to stable.
We have a fair number of APIs that have been experimental for more than
2 years. This policy amendment indicates that these APIs should be
promoted or removed, or should at least form a conservation between the
maintainer and original contributor.

Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
---
v2: addressing comments on abi expiry from Tyler Retzlaff.
v3: addressing typos in the git commit message

 doc/guides/contributing/abi_policy.rst | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
index 4ad87dbfed..840c295e5d 100644
--- a/doc/guides/contributing/abi_policy.rst
+++ b/doc/guides/contributing/abi_policy.rst
@@ -26,9 +26,10 @@ General Guidelines
    symbols is managed with :ref:`ABI Versioning <abi_versioning>`.
 #. The removal of symbols is considered an :ref:`ABI breakage <abi_breakages>`,
    once approved these will form part of the next ABI version.
-#. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may
-   be changed or removed without prior notice, as they are not considered part
-   of an ABI version.
+#. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may be
+   changed or removed without prior notice, as they are not considered part of
+   an ABI version. The :ref:`experimental <experimental_apis>` status of an API
+   is not an indefinite state.
 #. Updates to the :ref:`minimum hardware requirements <hw_rqmts>`, which drop
    support for hardware which was previously supported, should be treated as an
    ABI change.
@@ -358,3 +359,18 @@ Libraries
 Libraries marked as ``experimental`` are entirely not considered part of an ABI
 version.
 All functions in such libraries may be changed or removed without prior notice.
+
+Promotion to stable
+~~~~~~~~~~~~~~~~~~~
+
+Ordinarily APIs marked as ``experimental`` will be promoted to the stable ABI
+once a maintainer and/or the original contributor is satisfied that the API is
+reasonably mature. In exceptional circumstances, should an API still be
+classified as ``experimental`` after two years and is without any prospect of
+becoming part of the stable API. The API will then become a candidate for
+removal, to avoid the acculumation of abandoned symbols.
+
+Should an API's Binary Interface change during the two year period, usually due
+to a direct change in the to API's signature. It is reasonable for the expiry
+clock to reset. The promotion or removal of symbols will typically form part of
+a conversation between the maintainer and the original contributor.
-- 
2.26.2


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

* Re: [dpdk-dev] [PATCH v1] doc: policy on promotion of experimental APIs
  2021-07-01  7:56       ` Ferruh Yigit
@ 2021-07-01 14:45         ` Tyler Retzlaff
  0 siblings, 0 replies; 20+ messages in thread
From: Tyler Retzlaff @ 2021-07-01 14:45 UTC (permalink / raw)
  To: Ferruh Yigit; +Cc: Kinsella, Ray, dev, thomas, david.marchand, stephen

On Thu, Jul 01, 2021 at 08:56:22AM +0100, Ferruh Yigit wrote:
> On 6/30/2021 8:56 PM, Tyler Retzlaff wrote:
> > On Tue, Jun 29, 2021 at 07:38:05PM +0100, Kinsella, Ray wrote:
> >>
> >>
> >>>> +Promotion to stable
> >>>> +~~~~~~~~~~~~~~~~~~~
> >>>> +
> >>>> +Ordinarily APIs marked as ``experimental`` will be promoted to the stable API
> >>>> +once a maintainer and/or the original contributor is satisfied that the API is
> >>>> +reasonably mature. In exceptional circumstances, should an API still be
> >>>
> >>> this seems vague and arbitrary. is there a way we can have a more
> >>> quantitative metric for what "reasonably mature" means.
> >>>
> >>>> +classified as ``experimental`` after two years and is without any prospect of
> >>>> +becoming part of the stable API. The API will then become a candidate for
> >>>> +removal, to avoid the acculumation of abandoned symbols.
> >>>
> >>> i think with the above comment the basis for removal then depends on
> >>> whatever metric is used to determine maturity. 
> >>> if it is still changing
> >>> then it seems like it is useful and still evolving so perhaps should not
> >>> be removed but hasn't changed but doesn't meet the metric for being made
> >>> stable then perhaps it becomes a candidate for removal.
> >>
> >> Good idea. 
> >>
> >> I think it is reasonable to add a clause that indicates that any change 
> >> to the "API signature" would reset the clock.
> > 
> > a time based strategy works but i guess the follow-on to that is how is
> > the clock tracked and how does it get updated? i don't think trying to
> > troll through git history will be effective.
> > 
> 
> We are grouping the new experimental APIs in the version file based on the
> release they are added with a comment, thanks to Dave. Like:
> 
>         # added in 19.02
>         rte_extmem_attach;
>         rte_extmem_detach;
>         rte_extmem_register;
>         rte_extmem_unregister;
> 
>         # added in 19.05
>         rte_dev_dma_map;
>         rte_dev_dma_unmap;
>         ....
> 
> Please check 'lib/eal/version.map' as sample.
> 
> This enables us easily see the release experimental APIs are added.

this is fine but the subject being discussed is oriented around how long
an api/abi has been unchanged to identify it as a candidate for qualifying
it as stable (not experimental). are you suggesting that if api/abi changes
then it is moved to the -current version to "restart the clock" as it were?


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

* Re: [dpdk-dev] [PATCH v1] doc: policy on promotion of experimental APIs
  2021-07-01 10:19       ` Kinsella, Ray
@ 2021-07-01 15:09         ` Tyler Retzlaff
  2021-07-02  6:30           ` Kinsella, Ray
  0 siblings, 1 reply; 20+ messages in thread
From: Tyler Retzlaff @ 2021-07-01 15:09 UTC (permalink / raw)
  To: Kinsella, Ray; +Cc: dev, ferruh.yigit, thomas, david.marchand, stephen

On Thu, Jul 01, 2021 at 11:19:27AM +0100, Kinsella, Ray wrote:
> 
> 
> On 30/06/2021 20:56, Tyler Retzlaff wrote:
> > On Tue, Jun 29, 2021 at 07:38:05PM +0100, Kinsella, Ray wrote:
> >>
> >>
> >>>> +Promotion to stable
> >>>> +~~~~~~~~~~~~~~~~~~~
> >>>> +
> >>>> +Ordinarily APIs marked as ``experimental`` will be promoted to the stable API
> >>>> +once a maintainer and/or the original contributor is satisfied that the API is
> >>>> +reasonably mature. In exceptional circumstances, should an API still be
> >>>
> >>> this seems vague and arbitrary. is there a way we can have a more
> >>> quantitative metric for what "reasonably mature" means.
> >>>
> >>>> +classified as ``experimental`` after two years and is without any prospect of
> >>>> +becoming part of the stable API. The API will then become a candidate for
> >>>> +removal, to avoid the acculumation of abandoned symbols.
> >>>
> >>> i think with the above comment the basis for removal then depends on
> >>> whatever metric is used to determine maturity. 
> >>> if it is still changing
> >>> then it seems like it is useful and still evolving so perhaps should not
> >>> be removed but hasn't changed but doesn't meet the metric for being made
> >>> stable then perhaps it becomes a candidate for removal.
> >>
> >> Good idea. 
> >>
> >> I think it is reasonable to add a clause that indicates that any change 
> >> to the "API signature" would reset the clock.
> > 
> > a time based strategy works but i guess the follow-on to that is how is
> > the clock tracked and how does it get updated? i don't think trying to
> > troll through git history will be effective.
> > 
> > one nit, i think "api signature" doesn't cover all cases of what i would
> > regard as change. i would prefer to define it as "no change where api/abi
> > compatibility or semantic change occurred"? which is a lot more strict
> > but in practice is necessary to support binaries when abi/api is stable.
> > 
> > i.e. if a recompile is necessary with or without code change then it's a
> > change.
> 
> Having thought a bit ... this becomes a bit problematic.
> 
> Many data-structures in DPDK are nested, 
> these can have a ripple effect when changed - a change to mbuf is a good example.
> 
> What I saying is ...
> I don't think changes in ABI due to in-direct reasons should count.
> If there is a change due to a deliberate change in the ABI signature 
> that is fine, reset the clock.
>
> 
> If there is a change due to some nested data-structure, 
> 3-levels down changing in my book that doesn't count. 

it has to count otherwise dpdk's abi stability promise for major version
releases is meaningless. or are you suggesting it doesn't count for the
purpose of determining whether or not an experimental api/abi has
changed?

> As that may or may not have been deliberate, and is almost impossible to police. 
> 
> Checking anything but a deliberate change to the ABI signature,
> would be practically impossible IMHO. 

well, it isn't impossible but it does take knowledge, mechanism and
process maintain the abi for a major version.

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

* Re: [dpdk-dev] [PATCH v1] doc: policy on promotion of experimental APIs
  2021-07-01 15:09         ` Tyler Retzlaff
@ 2021-07-02  6:30           ` Kinsella, Ray
  0 siblings, 0 replies; 20+ messages in thread
From: Kinsella, Ray @ 2021-07-02  6:30 UTC (permalink / raw)
  To: Tyler Retzlaff; +Cc: dev, ferruh.yigit, thomas, david.marchand, stephen



On 01/07/2021 16:09, Tyler Retzlaff wrote:
> On Thu, Jul 01, 2021 at 11:19:27AM +0100, Kinsella, Ray wrote:
>>
>>
>> On 30/06/2021 20:56, Tyler Retzlaff wrote:
>>> On Tue, Jun 29, 2021 at 07:38:05PM +0100, Kinsella, Ray wrote:
>>>>
>>>>
>>>>>> +Promotion to stable
>>>>>> +~~~~~~~~~~~~~~~~~~~
>>>>>> +
>>>>>> +Ordinarily APIs marked as ``experimental`` will be promoted to the stable API
>>>>>> +once a maintainer and/or the original contributor is satisfied that the API is
>>>>>> +reasonably mature. In exceptional circumstances, should an API still be
>>>>>
>>>>> this seems vague and arbitrary. is there a way we can have a more
>>>>> quantitative metric for what "reasonably mature" means.
>>>>>
>>>>>> +classified as ``experimental`` after two years and is without any prospect of
>>>>>> +becoming part of the stable API. The API will then become a candidate for
>>>>>> +removal, to avoid the acculumation of abandoned symbols.
>>>>>
>>>>> i think with the above comment the basis for removal then depends on
>>>>> whatever metric is used to determine maturity. 
>>>>> if it is still changing
>>>>> then it seems like it is useful and still evolving so perhaps should not
>>>>> be removed but hasn't changed but doesn't meet the metric for being made
>>>>> stable then perhaps it becomes a candidate for removal.
>>>>
>>>> Good idea. 
>>>>
>>>> I think it is reasonable to add a clause that indicates that any change 
>>>> to the "API signature" would reset the clock.
>>>
>>> a time based strategy works but i guess the follow-on to that is how is
>>> the clock tracked and how does it get updated? i don't think trying to
>>> troll through git history will be effective.
>>>
>>> one nit, i think "api signature" doesn't cover all cases of what i would
>>> regard as change. i would prefer to define it as "no change where api/abi
>>> compatibility or semantic change occurred"? which is a lot more strict
>>> but in practice is necessary to support binaries when abi/api is stable.
>>>
>>> i.e. if a recompile is necessary with or without code change then it's a
>>> change.
>>
>> Having thought a bit ... this becomes a bit problematic.
>>
>> Many data-structures in DPDK are nested, 
>> these can have a ripple effect when changed - a change to mbuf is a good example.
>>
>> What I saying is ...
>> I don't think changes in ABI due to in-direct reasons should count.
>> If there is a change due to a deliberate change in the ABI signature 
>> that is fine, reset the clock.
>>
>>
>> If there is a change due to some nested data-structure, 
>> 3-levels down changing in my book that doesn't count. 
> 
> it has to count otherwise dpdk's abi stability promise for major version
> releases is meaningless. or are you suggesting it doesn't count for the
> purpose of determining whether or not an experimental api/abi has
> changed?
"it doesn't count for the purpose of determining whether or not an experimental api/abi has changed?".

Exactly - that is what I meant - apologies if I was unclear. 
In this case the change is not a deliberate act, 
in that it is not really happening because of any maturing of the ABI.

> 
>> As that may or may not have been deliberate, and is almost impossible to police. 
>>
>> Checking anything but a deliberate change to the ABI signature,
>> would be practically impossible IMHO. 
> 
> well, it isn't impossible but it does take knowledge, mechanism and
> process maintain the abi for a major version.

100% agree with this statement.

What do you think of the v3?


 

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

* Re: [dpdk-dev] [PATCH v3] doc: policy on the promotion of experimental APIs
  2021-07-01 10:38 ` [dpdk-dev] [PATCH v3] doc: policy on the " Ray Kinsella
@ 2021-07-07 18:32   ` Tyler Retzlaff
  2021-07-09  6:16   ` Jerin Jacob
  1 sibling, 0 replies; 20+ messages in thread
From: Tyler Retzlaff @ 2021-07-07 18:32 UTC (permalink / raw)
  To: Ray Kinsella
  Cc: dev, bruce.richardson, john.mcnamara, ferruh.yigit, thomas,
	david.marchand, stephen

On Thu, Jul 01, 2021 at 11:38:42AM +0100, Ray Kinsella wrote:
> Clarifying the ABI policy on the promotion of experimental APIS to stable.
> We have a fair number of APIs that have been experimental for more than
> 2 years. This policy amendment indicates that these APIs should be
> promoted or removed, or should at least form a conservation between the
> maintainer and original contributor.
> 
> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
> ---
Acked-By: Tyler Retzlaff <roretzla@microsoft.com>


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

* Re: [dpdk-dev] [PATCH v3] doc: policy on the promotion of experimental APIs
  2021-07-01 10:38 ` [dpdk-dev] [PATCH v3] doc: policy on the " Ray Kinsella
  2021-07-07 18:32   ` Tyler Retzlaff
@ 2021-07-09  6:16   ` Jerin Jacob
  2021-07-09 19:15     ` Tyler Retzlaff
  1 sibling, 1 reply; 20+ messages in thread
From: Jerin Jacob @ 2021-07-09  6:16 UTC (permalink / raw)
  To: Ray Kinsella
  Cc: dpdk-dev, Richardson, Bruce, John McNamara, roretzla,
	Ferruh Yigit, Thomas Monjalon, David Marchand, Stephen Hemminger

On Thu, Jul 1, 2021 at 4:08 PM Ray Kinsella <mdr@ashroe.eu> wrote:
>
> Clarifying the ABI policy on the promotion of experimental APIS to stable.
> We have a fair number of APIs that have been experimental for more than
> 2 years. This policy amendment indicates that these APIs should be
> promoted or removed, or should at least form a conservation between the
> maintainer and original contributor.
>
> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
> ---
> v2: addressing comments on abi expiry from Tyler Retzlaff.
> v3: addressing typos in the git commit message
>
>  doc/guides/contributing/abi_policy.rst | 22 +++++++++++++++++++---
>  1 file changed, 19 insertions(+), 3 deletions(-)
>
> diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
> index 4ad87dbfed..840c295e5d 100644
> --- a/doc/guides/contributing/abi_policy.rst
> +++ b/doc/guides/contributing/abi_policy.rst
> @@ -26,9 +26,10 @@ General Guidelines
>     symbols is managed with :ref:`ABI Versioning <abi_versioning>`.
>  #. The removal of symbols is considered an :ref:`ABI breakage <abi_breakages>`,
>     once approved these will form part of the next ABI version.
> -#. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may
> -   be changed or removed without prior notice, as they are not considered part
> -   of an ABI version.
> +#. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may be
> +   changed or removed without prior notice, as they are not considered part of
> +   an ABI version. The :ref:`experimental <experimental_apis>` status of an API
> +   is not an indefinite state.
>  #. Updates to the :ref:`minimum hardware requirements <hw_rqmts>`, which drop
>     support for hardware which was previously supported, should be treated as an
>     ABI change.
> @@ -358,3 +359,18 @@ Libraries
>  Libraries marked as ``experimental`` are entirely not considered part of an ABI
>  version.
>  All functions in such libraries may be changed or removed without prior notice.
> +
> +Promotion to stable
> +~~~~~~~~~~~~~~~~~~~
> +
> +Ordinarily APIs marked as ``experimental`` will be promoted to the stable ABI
> +once a maintainer and/or the original contributor is satisfied that the API is
> +reasonably mature. In exceptional circumstances, should an API still be

Is this line with git commit message?
Why making an exceptional case? why not make it stable after two years
or remove it.
My worry is if we make an exception case, it will be difficult to
enumerate the exception case.

> +classified as ``experimental`` after two years and is without any prospect of
> +becoming part of the stable API. The API will then become a candidate for
> +removal, to avoid the acculumation of abandoned symbols.
> +
> +Should an API's Binary Interface change during the two year period, usually due
> +to a direct change in the to API's signature. It is reasonable for the expiry
> +clock to reset. The promotion or removal of symbols will typically form part of
> +a conversation between the maintainer and the original contributor.
> --
> 2.26.2
>

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

* Re: [dpdk-dev] [PATCH v3] doc: policy on the promotion of experimental APIs
  2021-07-09  6:16   ` Jerin Jacob
@ 2021-07-09 19:15     ` Tyler Retzlaff
  2021-07-11  7:22       ` Jerin Jacob
  0 siblings, 1 reply; 20+ messages in thread
From: Tyler Retzlaff @ 2021-07-09 19:15 UTC (permalink / raw)
  To: Jerin Jacob
  Cc: Ray Kinsella, dpdk-dev, Richardson, Bruce, John McNamara,
	Ferruh Yigit, Thomas Monjalon, David Marchand, Stephen Hemminger

On Fri, Jul 09, 2021 at 11:46:54AM +0530, Jerin Jacob wrote:
> > +
> > +Promotion to stable
> > +~~~~~~~~~~~~~~~~~~~
> > +
> > +Ordinarily APIs marked as ``experimental`` will be promoted to the stable ABI
> > +once a maintainer and/or the original contributor is satisfied that the API is
> > +reasonably mature. In exceptional circumstances, should an API still be
> 
> Is this line with git commit message?
> Why making an exceptional case? why not make it stable after two years
> or remove it.
> My worry is if we make an exception case, it will be difficult to
> enumerate the exception case.

i think the intent here is to indicate that an api/abi doesn't just
automatically become stable after a period of time.  there also has to
be an evaluation by the maintainer / community before making it stable.

so i guess the timer is something that should force that evaluation. as
a part of that evaluation one would imagine there is justification for
keeping the api as experimental for longer and if so a rationale as to
why.

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

* Re: [dpdk-dev] [PATCH v3] doc: policy on the promotion of experimental APIs
  2021-07-09 19:15     ` Tyler Retzlaff
@ 2021-07-11  7:22       ` Jerin Jacob
  2021-08-03 14:12         ` Kinsella, Ray
  0 siblings, 1 reply; 20+ messages in thread
From: Jerin Jacob @ 2021-07-11  7:22 UTC (permalink / raw)
  To: Tyler Retzlaff
  Cc: Ray Kinsella, dpdk-dev, Richardson, Bruce, John McNamara,
	Ferruh Yigit, Thomas Monjalon, David Marchand, Stephen Hemminger

On Sat, Jul 10, 2021 at 12:46 AM Tyler Retzlaff
<roretzla@linux.microsoft.com> wrote:
>
> On Fri, Jul 09, 2021 at 11:46:54AM +0530, Jerin Jacob wrote:
> > > +
> > > +Promotion to stable
> > > +~~~~~~~~~~~~~~~~~~~
> > > +
> > > +Ordinarily APIs marked as ``experimental`` will be promoted to the stable ABI
> > > +once a maintainer and/or the original contributor is satisfied that the API is
> > > +reasonably mature. In exceptional circumstances, should an API still be
> >
> > Is this line with git commit message?
> > Why making an exceptional case? why not make it stable after two years
> > or remove it.
> > My worry is if we make an exception case, it will be difficult to
> > enumerate the exception case.
>
> i think the intent here is to indicate that an api/abi doesn't just
> automatically become stable after a period of time.  there also has to
> be an evaluation by the maintainer / community before making it stable.
>
> so i guess the timer is something that should force that evaluation. as
> a part of that evaluation one would imagine there is justification for
> keeping the api as experimental for longer and if so a rationale as to
> why.

I think, we need to have a deadline. Probably one year timer for evaluation and
two year for max time for decision to make it as stable or remove.

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

* Re: [dpdk-dev] [PATCH v3] doc: policy on the promotion of experimental APIs
  2021-07-11  7:22       ` Jerin Jacob
@ 2021-08-03 14:12         ` Kinsella, Ray
  0 siblings, 0 replies; 20+ messages in thread
From: Kinsella, Ray @ 2021-08-03 14:12 UTC (permalink / raw)
  To: Jerin Jacob, Tyler Retzlaff
  Cc: dpdk-dev, Richardson, Bruce, John McNamara, Ferruh Yigit,
	Thomas Monjalon, David Marchand, Stephen Hemminger



On 11/07/2021 08:22, Jerin Jacob wrote:
> On Sat, Jul 10, 2021 at 12:46 AM Tyler Retzlaff
> <roretzla@linux.microsoft.com> wrote:
>>
>> On Fri, Jul 09, 2021 at 11:46:54AM +0530, Jerin Jacob wrote:
>>>> +
>>>> +Promotion to stable
>>>> +~~~~~~~~~~~~~~~~~~~
>>>> +
>>>> +Ordinarily APIs marked as ``experimental`` will be promoted to the stable ABI
>>>> +once a maintainer and/or the original contributor is satisfied that the API is
>>>> +reasonably mature. In exceptional circumstances, should an API still be
>>>
>>> Is this line with git commit message?
>>> Why making an exceptional case? why not make it stable after two years
>>> or remove it.
>>> My worry is if we make an exception case, it will be difficult to
>>> enumerate the exception case.
>>
>> i think the intent here is to indicate that an api/abi doesn't just
>> automatically become stable after a period of time.  there also has to
>> be an evaluation by the maintainer / community before making it stable.
>>
>> so i guess the timer is something that should force that evaluation. as
>> a part of that evaluation one would imagine there is justification for
>> keeping the api as experimental for longer and if so a rationale as to
>> why.
> 
> I think, we need to have a deadline. Probably one year timer for evaluation and
> two year for max time for decision to make it as stable or remove.
> 

Tyler is correct here (sorry for the delay I was out on vacation). 
In my usage of the word exception - I was conveying that an API aging or timing out should be an exceptional event.
What I am hoping will happen in the 90%-ile of cases is conveyed in the previous line. 

"Ordinarily APIs marked as ``experimental`` will be promoted to the stable ABI
once a maintainer and/or the original contributor is satisfied that the API is
reasonably mature."

i.e. that the symbol has be pro-actively managed with the maintainer and original author deciding when to promote.

I will add a line to indicate that experimental apis should be reviewed after one year. 

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

* [dpdk-dev] [PATCH v4] doc: policy on the promotion of experimental APIs
  2021-06-29 16:00 [dpdk-dev] [PATCH v1] doc: policy on promotion of experimental APIs Ray Kinsella
                   ` (2 preceding siblings ...)
  2021-07-01 10:38 ` [dpdk-dev] [PATCH v3] doc: policy on the " Ray Kinsella
@ 2021-08-03 16:44 ` Ray Kinsella
  2021-08-04  9:34 ` [dpdk-dev] [PATCH v5] " Ray Kinsella
  4 siblings, 0 replies; 20+ messages in thread
From: Ray Kinsella @ 2021-08-03 16:44 UTC (permalink / raw)
  To: dev
  Cc: bruce.richardson, john.mcnamara, roretzla, ferruh.yigit, thomas,
	david.marchand, stephen, jerinjacobk, Ray Kinsella

Clarifying the ABI policy on the promotion of experimental APIS to stable.
We have a fair number of APIs that have been experimental for more than
2 years. This policy amendment indicates that these APIs should be
promoted or removed, or should at least form a conservation between the
maintainer and original contributor.

Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
Acked-by: Tyler Retzlaff <roretzla@linux.microsoft.com>
---
v2: addressing comments on abi expiry from Tyler Retzlaff.
v3: addressing typos in the git commit message
v4: addressing typos and comments by Jerin Jacob

 doc/guides/contributing/abi_policy.rst | 25 ++++++++++++++++++++++---
 1 file changed, 22 insertions(+), 3 deletions(-)

diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
index 4ad87dbfed..1acd12cbf4 100644
--- a/doc/guides/contributing/abi_policy.rst
+++ b/doc/guides/contributing/abi_policy.rst
@@ -26,9 +26,10 @@ General Guidelines
    symbols is managed with :ref:`ABI Versioning <abi_versioning>`.
 #. The removal of symbols is considered an :ref:`ABI breakage <abi_breakages>`,
    once approved these will form part of the next ABI version.
-#. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may
-   be changed or removed without prior notice, as they are not considered part
-   of an ABI version.
+#. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may be
+   changed or removed without prior notice, as they are not considered part of
+   an ABI version. The :ref:`experimental <experimental_apis>` status of an API
+   is not an indefinite state.
 #. Updates to the :ref:`minimum hardware requirements <hw_rqmts>`, which drop
    support for hardware which was previously supported, should be treated as an
    ABI change.
@@ -358,3 +359,21 @@ Libraries
 Libraries marked as ``experimental`` are entirely not considered part of an ABI
 version.
 All functions in such libraries may be changed or removed without prior notice.
+
+Promotion to stable
+~~~~~~~~~~~~~~~~~~~
+
+An API's ``experimental`` status should be reviewed annually, by both the
+maintainer and/or the original contributor. Ordinarily APIs marked as
+``experimental`` will be promoted to the stable ABI once a maintainer has become
+satisfied that the API is mature and is unlikely to change.
+
+In exceptional circumstances, should an API still be classified as
+``experimental`` after two years and is without any prospect of becoming part of
+the stable API. The API will then become a candidate for removal, to avoid the
+acculumation of abandoned symbols.
+
+Should an API's Binary Interface change, usually due to a direct change to the
+API's signature, it is reasonable for the review and expiry clocks to reset. The
+promotion or removal of symbols will typically form part of a conversation
+between the maintainer and the original contributor.
-- 
2.26.2


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

* [dpdk-dev] [PATCH v5] doc: policy on the promotion of experimental APIs
  2021-06-29 16:00 [dpdk-dev] [PATCH v1] doc: policy on promotion of experimental APIs Ray Kinsella
                   ` (3 preceding siblings ...)
  2021-08-03 16:44 ` [dpdk-dev] [PATCH v4] " Ray Kinsella
@ 2021-08-04  9:34 ` Ray Kinsella
  2021-08-04 10:39   ` Thomas Monjalon
  4 siblings, 1 reply; 20+ messages in thread
From: Ray Kinsella @ 2021-08-04  9:34 UTC (permalink / raw)
  To: dev
  Cc: bruce.richardson, john.mcnamara, roretzla, ferruh.yigit, thomas,
	david.marchand, stephen, jerinjacobk, Ray Kinsella

Clarifying the ABI policy on the promotion of experimental APIS to stable.
We have a fair number of APIs that have been experimental for more than
2 years. This policy amendment indicates that these APIs should be
promoted or removed, or should at least form a conservation between the
maintainer and original contributor.

Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
Acked-by: Tyler Retzlaff <roretzla@linux.microsoft.com>
---
v2: comments on abi expiry from Tyler Retzlaff.
v3: typos in the git commit message
v4: typos and comments by Jerin Jacob
v5: typos caught by the CI

 doc/guides/contributing/abi_policy.rst | 25 ++++++++++++++++++++++---
 1 file changed, 22 insertions(+), 3 deletions(-)

diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
index 4ad87dbfed..520763b63a 100644
--- a/doc/guides/contributing/abi_policy.rst
+++ b/doc/guides/contributing/abi_policy.rst
@@ -26,9 +26,10 @@ General Guidelines
    symbols is managed with :ref:`ABI Versioning <abi_versioning>`.
 #. The removal of symbols is considered an :ref:`ABI breakage <abi_breakages>`,
    once approved these will form part of the next ABI version.
-#. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may
-   be changed or removed without prior notice, as they are not considered part
-   of an ABI version.
+#. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may be
+   changed or removed without prior notice, as they are not considered part of
+   an ABI version. The :ref:`experimental <experimental_apis>` status of an API
+   is not an indefinite state.
 #. Updates to the :ref:`minimum hardware requirements <hw_rqmts>`, which drop
    support for hardware which was previously supported, should be treated as an
    ABI change.
@@ -358,3 +359,21 @@ Libraries
 Libraries marked as ``experimental`` are entirely not considered part of an ABI
 version.
 All functions in such libraries may be changed or removed without prior notice.
+
+Promotion to stable
+~~~~~~~~~~~~~~~~~~~
+
+An API's ``experimental`` status should be reviewed annually, by both the
+maintainer and/or the original contributor. Ordinarily APIs marked as
+``experimental`` will be promoted to the stable ABI once a maintainer has become
+satisfied that the API is mature and is unlikely to change.
+
+In exceptional circumstances, should an API still be classified as
+``experimental`` after two years and is without any prospect of becoming part of
+the stable API. The API will then become a candidate for removal, to avoid the
+accumulation of abandoned symbols.
+
+Should an API's Binary Interface change, usually due to a direct change to the
+API's signature, it is reasonable for the review and expiry clocks to reset. The
+promotion or removal of symbols will typically form part of a conversation
+between the maintainer and the original contributor.
-- 
2.26.2


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

* Re: [dpdk-dev] [PATCH v5] doc: policy on the promotion of experimental APIs
  2021-08-04  9:34 ` [dpdk-dev] [PATCH v5] " Ray Kinsella
@ 2021-08-04 10:39   ` Thomas Monjalon
  2021-08-04 11:49     ` Kinsella, Ray
  0 siblings, 1 reply; 20+ messages in thread
From: Thomas Monjalon @ 2021-08-04 10:39 UTC (permalink / raw)
  To: Ray Kinsella
  Cc: dev, bruce.richardson, john.mcnamara, roretzla, ferruh.yigit,
	david.marchand, stephen, jerinjacobk

04/08/2021 11:34, Ray Kinsella:
> Clarifying the ABI policy on the promotion of experimental APIS to stable.
> We have a fair number of APIs that have been experimental for more than
> 2 years. This policy amendment indicates that these APIs should be
> promoted or removed, or should at least form a conservation between the

s/conservation/conversation/

> maintainer and original contributor.
> 
> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
> Acked-by: Tyler Retzlaff <roretzla@linux.microsoft.com>
> ---
> +#. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may be
> +   changed or removed without prior notice, as they are not considered part of
> +   an ABI version. The :ref:`experimental <experimental_apis>` status of an API
> +   is not an indefinite state.
[...]
> +Promotion to stable
> +~~~~~~~~~~~~~~~~~~~
> +
> +An API's ``experimental`` status should be reviewed annually, by both the
> +maintainer and/or the original contributor. Ordinarily APIs marked as
> +``experimental`` will be promoted to the stable ABI once a maintainer has become
> +satisfied that the API is mature and is unlikely to change.
> +
> +In exceptional circumstances, should an API still be classified as
> +``experimental`` after two years and is without any prospect of becoming part of
> +the stable API. The API will then become a candidate for removal, to avoid the
> +accumulation of abandoned symbols.
> +
> +Should an API's Binary Interface change, usually due to a direct change to the

API's Binary Interface?
I assume you mean ABI.

> +API's signature, it is reasonable for the review and expiry clocks to reset. The
> +promotion or removal of symbols will typically form part of a conversation
> +between the maintainer and the original contributor.

Acked-by: Thomas Monjalon <thomas@monjalon.net>

Applied with above changes, thanks.



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

* Re: [dpdk-dev] [PATCH v5] doc: policy on the promotion of experimental APIs
  2021-08-04 10:39   ` Thomas Monjalon
@ 2021-08-04 11:49     ` Kinsella, Ray
  0 siblings, 0 replies; 20+ messages in thread
From: Kinsella, Ray @ 2021-08-04 11:49 UTC (permalink / raw)
  To: Thomas Monjalon
  Cc: dev, bruce.richardson, john.mcnamara, roretzla, ferruh.yigit,
	david.marchand, stephen, jerinjacobk



On 04/08/2021 11:39, Thomas Monjalon wrote:
> 04/08/2021 11:34, Ray Kinsella:
>> Clarifying the ABI policy on the promotion of experimental APIS to stable.
>> We have a fair number of APIs that have been experimental for more than
>> 2 years. This policy amendment indicates that these APIs should be
>> promoted or removed, or should at least form a conservation between the
> 
> s/conservation/conversation/
> 
>> maintainer and original contributor.
>>
>> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
>> Acked-by: Tyler Retzlaff <roretzla@linux.microsoft.com>
>> ---
>> +#. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may be
>> +   changed or removed without prior notice, as they are not considered part of
>> +   an ABI version. The :ref:`experimental <experimental_apis>` status of an API
>> +   is not an indefinite state.
> [...]
>> +Promotion to stable
>> +~~~~~~~~~~~~~~~~~~~
>> +
>> +An API's ``experimental`` status should be reviewed annually, by both the
>> +maintainer and/or the original contributor. Ordinarily APIs marked as
>> +``experimental`` will be promoted to the stable ABI once a maintainer has become
>> +satisfied that the API is mature and is unlikely to change.
>> +
>> +In exceptional circumstances, should an API still be classified as
>> +``experimental`` after two years and is without any prospect of becoming part of
>> +the stable API. The API will then become a candidate for removal, to avoid the
>> +accumulation of abandoned symbols.
>> +
>> +Should an API's Binary Interface change, usually due to a direct change to the
> 
> API's Binary Interface?
> I assume you mean ABI.
> 
>> +API's signature, it is reasonable for the review and expiry clocks to reset. The
>> +promotion or removal of symbols will typically form part of a conversation
>> +between the maintainer and the original contributor.
> 
> Acked-by: Thomas Monjalon <thomas@monjalon.net>
> 
> Applied with above changes, thanks.
> 

Thanks.

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

end of thread, other threads:[~2021-08-04 11:49 UTC | newest]

Thread overview: 20+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-06-29 16:00 [dpdk-dev] [PATCH v1] doc: policy on promotion of experimental APIs Ray Kinsella
2021-06-29 16:28 ` Tyler Retzlaff
2021-06-29 18:38   ` Kinsella, Ray
2021-06-30 19:56     ` Tyler Retzlaff
2021-07-01  7:56       ` Ferruh Yigit
2021-07-01 14:45         ` Tyler Retzlaff
2021-07-01 10:19       ` Kinsella, Ray
2021-07-01 15:09         ` Tyler Retzlaff
2021-07-02  6:30           ` Kinsella, Ray
2021-07-01 10:31 ` [dpdk-dev] [PATCH v2] " Ray Kinsella
2021-07-01 10:38 ` [dpdk-dev] [PATCH v3] doc: policy on the " Ray Kinsella
2021-07-07 18:32   ` Tyler Retzlaff
2021-07-09  6:16   ` Jerin Jacob
2021-07-09 19:15     ` Tyler Retzlaff
2021-07-11  7:22       ` Jerin Jacob
2021-08-03 14:12         ` Kinsella, Ray
2021-08-03 16:44 ` [dpdk-dev] [PATCH v4] " Ray Kinsella
2021-08-04  9:34 ` [dpdk-dev] [PATCH v5] " Ray Kinsella
2021-08-04 10:39   ` Thomas Monjalon
2021-08-04 11:49     ` Kinsella, Ray

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