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 16:29:50 +0000 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: Kevin Traynor , dev@dpdk.org, John McNamara , Marko Kovacevic Return-path: Received: from mga12.intel.com (mga12.intel.com [192.55.52.136]) by dpdk.org (Postfix) with ESMTP id 61D744F93 for ; Thu, 24 Jan 2019 17:29: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/24/2019 3:33 PM, Kevin Traynor wrote: > 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. OK, I will send a new versions with s/active/non-experimental/ > >>> >>> 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 >>>> ----------------- >>>> >>> >> >