From mboxrd@z Thu Jan 1 00:00:00 1970 From: Kevin Traynor Subject: Re: [PATCH v3 3/3] doc: add deprecation marker usage Date: Thu, 24 Jan 2019 16:33:19 +0100 Message-ID: References: <20181221155719.89773-1-ferruh.yigit@intel.com> <20190122162310.53613-1-ferruh.yigit@intel.com> <20190122162310.53613-3-ferruh.yigit@intel.com> <322d6651-3520-4c07-4bf2-e605da06f525@intel.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 7bit Cc: Luca Boccassi , Yongseok Koh , Neil Horman To: Ferruh Yigit , dev@dpdk.org, John McNamara , Marko Kovacevic Return-path: Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by dpdk.org (Postfix) with ESMTP id BFB294C94 for ; Thu, 24 Jan 2019 16:33:23 +0100 (CET) In-Reply-To: <322d6651-3520-4c07-4bf2-e605da06f525@intel.com> Content-Language: en-US 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 01/24/2019 03:31 PM, Ferruh Yigit wrote: > On 1/23/2019 11:07 PM, Kevin Traynor wrote: >> On 01/22/2019 05:23 PM, Ferruh Yigit wrote: >>> Define '__rte_deprecated' usage process. >>> >>> Suggests keeping old API with '__rte_deprecated' marker including >>> next LTS, they will be removed just after the LTS release. >>> >>> Signed-off-by: Ferruh Yigit >>> Acked-by: Luca Boccassi >>> --- >>> Cc: Luca Boccassi >>> Cc: Kevin Traynor >>> Cc: Yongseok Koh >>> Cc: Neil Horman >>> >>> v2: >>> * Rephrased as commented >>> >>> v3: >>> * changed when to remove the deprecated API. It is now just after >>> an LTS release, the motivation is to keep changes small in LTS. >>> Based on techboard discussion: >>> http://mails.dpdk.org/archives/dev/2019-January/123519.html >>> --- >>> doc/guides/contributing/versioning.rst | 9 +++++++++ >>> 1 file changed, 9 insertions(+) >>> >>> diff --git a/doc/guides/contributing/versioning.rst b/doc/guides/contributing/versioning.rst >>> index bfc27fbe0..977d06c60 100644 >>> --- a/doc/guides/contributing/versioning.rst >>> +++ b/doc/guides/contributing/versioning.rst >>> @@ -125,6 +125,15 @@ added to the Release Notes: >>> these changes. Binaries using this library built prior to version 2.1 will >>> require updating and recompilation. >>> >>> +New API replacing previous one >>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ >>> + >>> +If a new API proposed functionally replaces an existing one, when the >>> +new API becomes active then the old one is marked with ``__rte_deprecated``. >> >> I don't think it's clear what 'active' means here. Can it be re-phrased >> as something like "..when the new API has it's experimental tag removed, >> then the old one..". > > This was what in my mind by 'active' but didn't want to create confusion with > details, and really it doesn't matter the "experimental" detail, by any means if > the new API is not 'active' we shouldn't mark the old one as 'deprecated'. > > But agree can be defined better than 'active'. Do you have any suggestion here, > 'GA', 'public', 'official', 'supported'? > How about 'non-experimental' ? I think it would make it clear in meaning for general reading and also avoid a mis-interpretation of what the actual detail is. >> >> It might also be worth mentioning the reasoning behind this, perhaps >> something like: This is so an application continues to be provided with >> at least one stable (non-deprecated/non-experimental) API for this >> functionality. >> >>> +Deprecated APIs removed completely just after the next LTS. >>> + >>> +Reminder that new API should follow deprecation process to become active. >>> + >>> >>> Experimental APIs >>> ----------------- >>> >> >