From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 2CCBBA0A0C; Thu, 1 Jul 2021 16:45:14 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 0F4F44067C; Thu, 1 Jul 2021 16:45:14 +0200 (CEST) Received: from linux.microsoft.com (linux.microsoft.com [13.77.154.182]) by mails.dpdk.org (Postfix) with ESMTP id 9E4D340141 for ; Thu, 1 Jul 2021 16:45:12 +0200 (CEST) Received: by linux.microsoft.com (Postfix, from userid 1086) id EA69320B7178; Thu, 1 Jul 2021 07:45:11 -0700 (PDT) DKIM-Filter: OpenDKIM Filter v2.11.0 linux.microsoft.com EA69320B7178 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linux.microsoft.com; s=default; t=1625150711; bh=tgE9JouZS3lcDZ6+djn7b2bDqJ9TlbAJK6KAdX8LOBk=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=UTloksAunvUnKj7evPg51B/X8FVtaoo0c6c+LnuQjGfyEMOtt3/ZeBblzphnSctV1 S2FIh1MTb5qVIDbk6QVTmUpjZv010wOrDBc02l+hDPpA+J5lzwf4n1NhBSqEXLSStg D1gBKZJewxVJdORc8JpKzWEGIWmjlWBQTe4JufLs= Date: Thu, 1 Jul 2021 07:45:11 -0700 From: Tyler Retzlaff To: Ferruh Yigit Cc: "Kinsella, Ray" , dev@dpdk.org, thomas@monjalon.net, david.marchand@redhat.com, stephen@networkplumber.org Message-ID: <20210701144511.GA4202@linuxonhyperv3.guj3yctzbm1etfxqx2vob5hsef.xx.internal.cloudapp.net> References: <20210629160031.74681-1-mdr@ashroe.eu> <20210629162837.GB27963@linuxonhyperv3.guj3yctzbm1etfxqx2vob5hsef.xx.internal.cloudapp.net> <46fa9dec-cee0-ba7f-13a0-11ee42419ee5@ashroe.eu> <20210630195617.GA24715@linuxonhyperv3.guj3yctzbm1etfxqx2vob5hsef.xx.internal.cloudapp.net> <17c1acba-b67c-43b1-cd65-e29d8d75c549@intel.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <17c1acba-b67c-43b1-cd65-e29d8d75c549@intel.com> User-Agent: Mutt/1.5.21 (2010-09-15) Subject: Re: [dpdk-dev] [PATCH v1] doc: policy on promotion of experimental APIs X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" 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?