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 03E1B201 for ; Thu, 24 Jan 2019 00:07:28 +0100 (CET) Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 2E1DCAB423; Wed, 23 Jan 2019 23:07:27 +0000 (UTC) Received: from ktraynor.remote.csb (ovpn-116-24.ams2.redhat.com [10.36.116.24]) by smtp.corp.redhat.com (Postfix) with ESMTP id 50533424A; Wed, 23 Jan 2019 23:07:23 +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> From: Kevin Traynor Organization: Red Hat Message-ID: Date: Thu, 24 Jan 2019 00:07:22 +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: <20190122162310.53613-3-ferruh.yigit@intel.com> Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.28]); Wed, 23 Jan 2019 23:07:28 +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: Wed, 23 Jan 2019 23:07:29 -0000 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..". 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 > ----------------- >