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 C6999A0A0C; Tue, 29 Jun 2021 20:38:18 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 8C6F4411A5; Tue, 29 Jun 2021 20:38:18 +0200 (CEST) Received: from mail-108-mta11.mxroute.com (mail-108-mta11.mxroute.com [136.175.108.11]) by mails.dpdk.org (Postfix) with ESMTP id 1A84C40E01 for ; Tue, 29 Jun 2021 20:38:16 +0200 (CEST) Received: from filter004.mxroute.com ([149.28.56.236] filter004.mxroute.com) (Authenticated sender: mN4UYu2MZsgR) by mail-108-mta11.mxroute.com (ZoneMTA) with ESMTPSA id 17a59107eff0002d34.001 for (version=TLSv1/SSLv3 cipher=ECDHE-RSA-AES128-GCM-SHA256); Tue, 29 Jun 2021 18:38:11 +0000 X-Zone-Loop: d7a7dc769c7b0354c98226a1fe50311a8c50f5c1d434 X-Originating-IP: [149.28.56.236] DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=ashroe.eu; s=x; h=Content-Transfer-Encoding:Content-Type:In-Reply-To:MIME-Version:Date: Message-ID:From:References:Cc:To:Subject:Sender:Reply-To:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:List-Id:List-Help:List-Unsubscribe:List-Subscribe: List-Post:List-Owner:List-Archive; bh=471yAHHJeUfiE8fhYO19SLynIP/ljGbmMHoLI51Vy6k=; b=KnB7JhCG2zUlxMcrsvFfx4um50 KbWQRE4wz8u1UbjkA+zw4pDfbw6VHz7iQ248GHjq+i1UeYYn76O6KiCe1aWHZ4rstQD6zmEMa2NAC m2EFyFuPMFiaP9NYCc1i/v6CjyCDEF6tZt7AmXRzJHdiwfjKLbdE+kgUUFRk2xW5UdzGPtAqxPPoi Koiw8oZ2C0IZgx2k195aiV/znYEXoEIeXziLWxk6T9V5jX8GN65YmudPhuS/tgq8bUBtICANdhQBT sd+kKMnbpVhOB8gOOIwlBBGRfAx2flSb5DRbn17YCTrgTZAV4gRlQm7Mnu/wi5ZUDOZvHHJDxesWM ChA0h3ew==; To: Tyler Retzlaff Cc: dev@dpdk.org, ferruh.yigit@intel.com, 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> From: "Kinsella, Ray" Message-ID: <46fa9dec-cee0-ba7f-13a0-11ee42419ee5@ashroe.eu> Date: Tue, 29 Jun 2021 19:38:05 +0100 User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:78.0) Gecko/20100101 Thunderbird/78.11.0 MIME-Version: 1.0 In-Reply-To: <20210629162837.GB27963@linuxonhyperv3.guj3yctzbm1etfxqx2vob5hsef.xx.internal.cloudapp.net> Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit X-AuthUser: mdr@ashroe.eu X-Zone-Spam-Resolution: no action X-Zone-Spam-Status: No, score=-0.1, required=15, tests=[ARC_NA=0, FROM_HAS_DN=0, TO_DN_SOME=0, MIME_GOOD=-0.1, FROM_EQ_ENVFROM=0, MIME_TRACE=0, RCVD_COUNT_ZERO=0, RCPT_COUNT_FIVE=0, MID_RHS_MATCH_FROM=0, NEURAL_SPAM=0] 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 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 >> --- >> 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 `. >> #. The removal of symbols is considered an :ref:`ABI breakage `, >> once approved these will form part of the next ABI version. >> -#. Libraries or APIs marked as :ref:`experimental ` 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 ` may be >> + changed or removed without prior notice, as they are not considered part of >> + an ABI version. The :ref:`experimental ` status of an API >> + is not an indefinite state. >> #. Updates to the :ref:`minimum hardware requirements `, 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. >