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 F3586A0C45; Wed, 4 Aug 2021 11:36:28 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 73E5B4014F; Wed, 4 Aug 2021 11:36:28 +0200 (CEST) Received: from mga18.intel.com (mga18.intel.com [134.134.136.126]) by mails.dpdk.org (Postfix) with ESMTP id D0BA94003E for ; Wed, 4 Aug 2021 11:36:26 +0200 (CEST) X-IronPort-AV: E=McAfee;i="6200,9189,10065"; a="201072782" X-IronPort-AV: E=Sophos;i="5.84,293,1620716400"; d="scan'208";a="201072782" Received: from fmsmga006.fm.intel.com ([10.253.24.20]) by orsmga106.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 04 Aug 2021 02:36:25 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.84,293,1620716400"; d="scan'208";a="667771565" Received: from silpixa00396680.ir.intel.com (HELO silpixa00396680.ger.corp.intel.com) ([10.237.223.54]) by fmsmga006.fm.intel.com with ESMTP; 04 Aug 2021 02:36:22 -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, jerinjacobk@gmail.com, Ray Kinsella Date: Wed, 4 Aug 2021 10:34:31 +0100 Message-Id: <20210804093431.677707-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 v5] 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 Acked-by: Tyler Retzlaff --- v2: comments on abi expiry from Tyler Retzlaff. v3: typos in the git commit message v4: typos and comments by Jerin Jacob v5: typos caught by the CI doc/guides/contributing/abi_policy.rst | 25 ++++++++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst index 4ad87dbfed..520763b63a 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,21 @@ 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 +~~~~~~~~~~~~~~~~~~~ + +An API's ``experimental`` status should be reviewed annually, by both the +maintainer and/or the original contributor. Ordinarily APIs marked as +``experimental`` will be promoted to the stable ABI once a maintainer has become +satisfied that the API is mature and is unlikely to change. + +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 +accumulation of abandoned symbols. + +Should an API's Binary Interface change, usually due to a direct change to the +API's signature, it is reasonable for the review and expiry clocks 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