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 152AAA0A0C; Thu, 1 Jul 2021 09:56:34 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 90ADF40141; Thu, 1 Jul 2021 09:56:33 +0200 (CEST) Received: from mga09.intel.com (mga09.intel.com [134.134.136.24]) by mails.dpdk.org (Postfix) with ESMTP id A0F3B40040 for ; Thu, 1 Jul 2021 09:56:31 +0200 (CEST) X-IronPort-AV: E=McAfee;i="6200,9189,10031"; a="208443924" X-IronPort-AV: E=Sophos;i="5.83,313,1616482800"; d="scan'208";a="208443924" Received: from orsmga007.jf.intel.com ([10.7.209.58]) by orsmga102.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 01 Jul 2021 00:56:29 -0700 X-IronPort-AV: E=Sophos;i="5.83,313,1616482800"; d="scan'208";a="447791671" Received: from fyigit-mobl1.ger.corp.intel.com (HELO [10.213.218.233]) ([10.213.218.233]) by orsmga007-auth.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 01 Jul 2021 00:56:25 -0700 To: Tyler Retzlaff , "Kinsella, Ray" Cc: dev@dpdk.org, thomas@monjalon.net, david.marchand@redhat.com, stephen@networkplumber.org 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> From: Ferruh Yigit X-User: ferruhy Message-ID: <17c1acba-b67c-43b1-cd65-e29d8d75c549@intel.com> Date: Thu, 1 Jul 2021 08:56:22 +0100 MIME-Version: 1.0 In-Reply-To: <20210630195617.GA24715@linuxonhyperv3.guj3yctzbm1etfxqx2vob5hsef.xx.internal.cloudapp.net> Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 8bit 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 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. >>>