From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id DD4F4A055A; Tue, 25 Feb 2020 16:35:51 +0100 (CET) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 29F701F1C; Tue, 25 Feb 2020 16:35:51 +0100 (CET) Received: from smtp.tuxdriver.com (charlotte.tuxdriver.com [70.61.120.58]) by dpdk.org (Postfix) with ESMTP id 225EAA3 for ; Tue, 25 Feb 2020 16:35:50 +0100 (CET) Received: from 2606-a000-111b-43ee-0000-0000-0000-1bf2.inf6.spectrum.com ([2606:a000:111b:43ee::1bf2] helo=localhost) by smtp.tuxdriver.com with esmtpsa (TLSv1:AES256-SHA:256) (Exim 4.63) (envelope-from ) id 1j6cFJ-0002H7-H9; Tue, 25 Feb 2020 10:35:46 -0500 Date: Tue, 25 Feb 2020 10:35:40 -0500 From: Neil Horman To: Ray Kinsella Cc: dev@dpdk.org, john.mcnamara@intel.com, ferruh.yigit@intel.com, marko.kovacevic@intel.co Message-ID: <20200225153540.GA375824@hmswarspite.think-freely.org> References: <1580915872-1686-1-git-send-email-mdr@ashroe.eu> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <1580915872-1686-1-git-send-email-mdr@ashroe.eu> X-Spam-Score: -2.9 (--) X-Spam-Status: No Subject: Re: [dpdk-dev] [PATCH] doc: alias to experimental tag for stable apis X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 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 Wed, Feb 05, 2020 at 03:17:52PM +0000, Ray Kinsella wrote: > When a maintainer is promoting an API to become part of the next major ABI > version by removing the experimental tag, possibly a few releases in advance of > the declaration of the next ABI version. The maintainer may choose to offer an > alias to the experimental tag, as removing the tag before the declaration of the > next major ABI version, would cause an ABI breakage for applications using the > API. > > Signed-off-by: Ray Kinsella > --- > doc/guides/contributing/abi_policy.rst | 10 ++++++++++ > 1 file changed, 10 insertions(+) > > diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst > index 05ca959..9a4a102 100644 > --- a/doc/guides/contributing/abi_policy.rst > +++ b/doc/guides/contributing/abi_policy.rst > @@ -159,6 +159,11 @@ The requirements for changing the ABI are: > ``experimental``, as described in the section on :ref:`Experimental APIs > and Libraries `. > > + - In situations where an ``experimental`` API has been stable for some time. > + When promoting the API to become part of the next ABI version, the > + maintainer may choose to provide an alias to the ``experimental`` tag, so > + as not to break consuming applications. > + I don't have any issue with the approach, but just to ask the question, is it worth providing an example here, of how exactly to do this? The use of VERSION_SYMBOL isn't often used, and so may be non-obvious. Actually, as I look at it, the VERSION_SYMBOL macro assume a DPDK_ prefix on the version string, which works for versioned symbols, but not for the EXPERIMENTAL symbol version (no DPDK_ prefix). We should probably create a variant of the VERSION_SYMBOL macro to allow aliasing to the EXPERIMENTAL version, something like ALIAS_TO_EXPERIMENTAL() or some such Neil > #. If a newly proposed API functionally replaces an existing one, when the new > API becomes non-experimental, then the old one is marked with > ``__rte_deprecated``. > @@ -317,6 +322,11 @@ not required. Though, an API should remain in experimental state for at least > one release. Thereafter, the normal process of posting patch for review to > mailing list can be followed. > > +After the experimental tag has been formally removed, a tree/sub-tree maintainer > +may choose to offer an alias to the experimental tag so as not to break > +applications using the API. This alias can then be dropped at the declaration of > +next major ABI version. > + > Libraries > ~~~~~~~~~ > > -- > 2.7.4 > >