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 <ferruh.yi...@intel.com> >>> Acked-by: Luca Boccassi <bl...@debian.org> >>> --- >>> Cc: Luca Boccassi <bl...@debian.org> >>> Cc: Kevin Traynor <ktray...@redhat.com> >>> Cc: Yongseok Koh <ys...@mellanox.com> >>> Cc: Neil Horman <nhor...@tuxdriver.com> >>> >>> 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 >>> ----------------- >>> >> >
