[dpdk-dev] [PATCH v3 3/3] doc: add deprecation marker usage
Kevin Traynor
ktraynor at redhat.com
Thu Jan 24 00:07:22 CET 2019
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.yigit at intel.com>
> Acked-by: Luca Boccassi <bluca at debian.org>
> ---
> Cc: Luca Boccassi <bluca at debian.org>
> Cc: Kevin Traynor <ktraynor at redhat.com>
> Cc: Yongseok Koh <yskoh at mellanox.com>
> Cc: Neil Horman <nhorman at 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..".
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
> -----------------
>
More information about the dev
mailing list