From mboxrd@z Thu Jan 1 00:00:00 1970 From: Ferruh Yigit Subject: Re: [PATCH v3 3/3] doc: add deprecation marker usage Date: Thu, 24 Jan 2019 14:31:50 +0000 Message-ID: <322d6651-3520-4c07-4bf2-e605da06f525@intel.com> References: <20181221155719.89773-1-ferruh.yigit@intel.com> <20190122162310.53613-1-ferruh.yigit@intel.com> <20190122162310.53613-3-ferruh.yigit@intel.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Cc: Luca Boccassi , Yongseok Koh , Neil Horman To: Kevin Traynor , dev@dpdk.org, John McNamara , Marko Kovacevic Return-path: Received: from mga09.intel.com (mga09.intel.com [134.134.136.24]) by dpdk.org (Postfix) with ESMTP id 9891C324D for ; Thu, 24 Jan 2019 15:31:54 +0100 (CET) In-Reply-To: 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 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'? > > 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 >> ----------------- >> >