From mboxrd@z Thu Jan 1 00:00:00 1970 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) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id DBAB581DFA; Thu, 24 Jan 2019 15:33:22 +0000 (UTC) Received: from ktraynor.remote.csb (ovpn-117-82.ams2.redhat.com [10.36.117.82]) by smtp.corp.redhat.com (Postfix) with ESMTP id 2ACBE1000049; Thu, 24 Jan 2019 15:33:20 +0000 (UTC) To: Ferruh Yigit , dev@dpdk.org, John McNamara , Marko Kovacevic Cc: Luca Boccassi , Yongseok Koh , Neil Horman 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> From: Kevin Traynor Organization: Red Hat Message-ID: Date: Thu, 24 Jan 2019 16:33:19 +0100 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.2.0 MIME-Version: 1.0 In-Reply-To: <322d6651-3520-4c07-4bf2-e605da06f525@intel.com> Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.25]); Thu, 24 Jan 2019 15:33:22 +0000 (UTC) Subject: Re: [dpdk-dev] [PATCH v3 3/3] doc: add deprecation marker usage 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: , X-List-Received-Date: Thu, 24 Jan 2019 15:33:24 -0000 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 >>> ----------------- >>> >> >