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 <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.
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 >>>> ----------------- >>>> >>> >> >
