From patchwork Tue Jun 29 16:00:31 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Ray Kinsella X-Patchwork-Id: 94987 X-Patchwork-Delegate: thomas@monjalon.net Return-Path: X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 9742AA0C3F; Tue, 29 Jun 2021 18:01:06 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 27C3F4117E; Tue, 29 Jun 2021 18:01:06 +0200 (CEST) Received: from mga09.intel.com (mga09.intel.com [134.134.136.24]) by mails.dpdk.org (Postfix) with ESMTP id BF3AC40E01 for ; Tue, 29 Jun 2021 18:01:04 +0200 (CEST) X-IronPort-AV: E=McAfee;i="6200,9189,10030"; a="208121458" X-IronPort-AV: E=Sophos;i="5.83,309,1616482800"; d="scan'208";a="208121458" Received: from fmsmga008.fm.intel.com ([10.253.24.58]) by orsmga102.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 29 Jun 2021 09:00:43 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.83,309,1616482800"; d="scan'208";a="456833717" Received: from silpixa00396680.ir.intel.com (HELO silpixa00396680.ger.corp.intel.com) ([10.237.223.54]) by fmsmga008.fm.intel.com with ESMTP; 29 Jun 2021 09:00:35 -0700 From: Ray Kinsella To: dev@dpdk.org Cc: ferruh.yigit@intel.com, thomas@monjalon.net, david.marchand@redhat.com, stephen@networkplumber.org, Ray Kinsella Date: Tue, 29 Jun 2021 17:00:31 +0100 Message-Id: <20210629160031.74681-1-mdr@ashroe.eu> X-Mailer: git-send-email 2.26.2 MIME-Version: 1.0 Subject: [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" 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 +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. + +The promotion or removal of symbols will typically form part of a conversation +between the maintainer and the original contributor.