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 9B1AEA0547; Tue, 3 Aug 2021 18:46:53 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 5E6F8411A7; Tue, 3 Aug 2021 18:46:53 +0200 (CEST) Received: from mga12.intel.com (mga12.intel.com [192.55.52.136]) by mails.dpdk.org (Postfix) with ESMTP id B7AA940E3C for ; Tue, 3 Aug 2021 18:46:51 +0200 (CEST) X-IronPort-AV: E=McAfee;i="6200,9189,10065"; a="193326066" X-IronPort-AV: E=Sophos;i="5.84,292,1620716400"; d="scan'208";a="193326066" Received: from fmsmga008.fm.intel.com ([10.253.24.58]) by fmsmga106.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 03 Aug 2021 09:46:50 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.84,292,1620716400"; d="scan'208";a="479591680" Received: from silpixa00396680.ir.intel.com (HELO silpixa00396680.ger.corp.intel.com) ([10.237.223.54]) by fmsmga008.fm.intel.com with ESMTP; 03 Aug 2021 09:46:48 -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: Tue, 3 Aug 2021 17:44:43 +0100 Message-Id: <20210803164443.672505-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 v4] 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: addressing comments on abi expiry from Tyler Retzlaff. v3: addressing typos in the git commit message v4: addressing typos and comments by Jerin Jacob 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..1acd12cbf4 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 +acculumation 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