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 5D70CA0C3F; Tue, 29 Jun 2021 18:28:40 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 291A2411A5; Tue, 29 Jun 2021 18:28:40 +0200 (CEST) Received: from linux.microsoft.com (linux.microsoft.com [13.77.154.182]) by mails.dpdk.org (Postfix) with ESMTP id 2ADAC40E01 for ; Tue, 29 Jun 2021 18:28:38 +0200 (CEST) Received: by linux.microsoft.com (Postfix, from userid 1086) id 803F920B7178; Tue, 29 Jun 2021 09:28:37 -0700 (PDT) DKIM-Filter: OpenDKIM Filter v2.11.0 linux.microsoft.com 803F920B7178 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linux.microsoft.com; s=default; t=1624984117; bh=+fU5njwVpTBnnsalw+7diPtvLn7s+NKe0OYZwdGi29I=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=h/2wO3vXfWQy17hG7CF1aeX41bbpYiPaqpZUgSvsNxosGe1KfbyTq93xXv3wBGkh4 jf1x7VrgbbJ/VYjDe4Bu6BkjEkI0BKHY5UD6bT90VirCV8gz4PjDU2gkROhYVYnB70 JBhaW9lYOM+9aqdldDAn2SqvM5Qs06VBBjtf6gIc= Date: Tue, 29 Jun 2021 09:28:37 -0700 From: Tyler Retzlaff To: Ray Kinsella Cc: dev@dpdk.org, ferruh.yigit@intel.com, thomas@monjalon.net, david.marchand@redhat.com, stephen@networkplumber.org Message-ID: <20210629162837.GB27963@linuxonhyperv3.guj3yctzbm1etfxqx2vob5hsef.xx.internal.cloudapp.net> References: <20210629160031.74681-1-mdr@ashroe.eu> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20210629160031.74681-1-mdr@ashroe.eu> 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 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. > + > +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.