DPDK patches and discussions
 help / color / mirror / Atom feed
From: Ferruh Yigit <ferruh.yigit@intel.com>
To: Tyler Retzlaff <roretzla@linux.microsoft.com>,
	"Kinsella, Ray" <mdr@ashroe.eu>
Cc: dev@dpdk.org, thomas@monjalon.net, david.marchand@redhat.com,
	stephen@networkplumber.org
Subject: Re: [dpdk-dev] [PATCH v1] doc: policy on promotion of experimental APIs
Date: Thu, 1 Jul 2021 08:56:22 +0100	[thread overview]
Message-ID: <17c1acba-b67c-43b1-cd65-e29d8d75c549@intel.com> (raw)
In-Reply-To: <20210630195617.GA24715@linuxonhyperv3.guj3yctzbm1etfxqx2vob5hsef.xx.internal.cloudapp.net>

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


  reply	other threads:[~2021-07-01  7:56 UTC|newest]

Thread overview: 20+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-06-29 16:00 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 [this message]
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

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=17c1acba-b67c-43b1-cd65-e29d8d75c549@intel.com \
    --to=ferruh.yigit@intel.com \
    --cc=david.marchand@redhat.com \
    --cc=dev@dpdk.org \
    --cc=mdr@ashroe.eu \
    --cc=roretzla@linux.microsoft.com \
    --cc=stephen@networkplumber.org \
    --cc=thomas@monjalon.net \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).