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 5CDBDA0A0C; Thu, 1 Jul 2021 12:38:56 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id F2BAF40141; Thu, 1 Jul 2021 12:38:55 +0200 (CEST) Received: from mga12.intel.com (mga12.intel.com [192.55.52.136]) by mails.dpdk.org (Postfix) with ESMTP id 26A9A40040 for ; Thu, 1 Jul 2021 12:38:53 +0200 (CEST) X-IronPort-AV: E=McAfee;i="6200,9189,10031"; a="188194694" X-IronPort-AV: E=Sophos;i="5.83,313,1616482800"; d="scan'208";a="188194694" Received: from orsmga002.jf.intel.com ([10.7.209.21]) by fmsmga106.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 01 Jul 2021 03:38:53 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.83,313,1616482800"; d="scan'208";a="426125386" Received: from silpixa00396680.ir.intel.com (HELO silpixa00396680.ger.corp.intel.com) ([10.237.223.54]) by orsmga002.jf.intel.com with ESMTP; 01 Jul 2021 03:38:50 -0700 From: Ray Kinsella To: dev@dpdk.org Cc: bruce.richardson@intel.com, john.mcnamara@intel.com, roretzla@linux.microsoft.com, ferruh.yigit@intel.com, thomas@monjalon.net, david.marchand@redhat.com, stephen@networkplumber.org, Ray Kinsella Date: Thu, 1 Jul 2021 11:38:42 +0100 Message-Id: <20210701103842.161275-1-mdr@ashroe.eu> X-Mailer: git-send-email 2.26.2 In-Reply-To: <20210629160031.74681-1-mdr@ashroe.eu> References: <20210629160031.74681-1-mdr@ashroe.eu> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] [PATCH v3] doc: policy on the 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" 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 amendment 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 --- v2: addressing comments on abi expiry from Tyler Retzlaff. v3: addressing typos in the git commit message doc/guides/contributing/abi_policy.rst | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst index 4ad87dbfed..840c295e5d 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,18 @@ 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 ABI +once a maintainer and/or the original contributor is satisfied that the API is +reasonably mature. In exceptional circumstances, should an API still be +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. + +Should an API's Binary Interface change during the two year period, usually due +to a direct change in the to API's signature. It is reasonable for the expiry +clock to reset. The promotion or removal of symbols will typically form part of +a conversation between the maintainer and the original contributor. -- 2.26.2