DPDK patches and discussions
 help / color / mirror / Atom feed
From: Neil Horman <nhorman@tuxdriver.com>
To: Ray Kinsella <mdr@ashroe.eu>
Cc: dev@dpdk.org, john.mcnamara@intel.com, ferruh.yigit@intel.com,
	marko.kovacevic@intel.co
Subject: Re: [dpdk-dev] [PATCH] doc: alias to experimental tag for stable apis
Date: Tue, 25 Feb 2020 10:35:40 -0500
Message-ID: <20200225153540.GA375824@hmswarspite.think-freely.org> (raw)
In-Reply-To: <1580915872-1686-1-git-send-email-mdr@ashroe.eu>

On Wed, Feb 05, 2020 at 03:17:52PM +0000, Ray Kinsella wrote:
> When a maintainer is promoting an API to become part of the next major ABI
> version by removing the experimental tag, possibly a few releases in advance of
> the declaration of the next ABI version. The maintainer may choose to offer an
> alias to the experimental tag, as removing the tag before the declaration of the
> next major ABI version, would cause an ABI breakage for applications using the
> API.
> 
> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
> ---
>  doc/guides/contributing/abi_policy.rst | 10 ++++++++++
>  1 file changed, 10 insertions(+)
> 
> diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
> index 05ca959..9a4a102 100644
> --- a/doc/guides/contributing/abi_policy.rst
> +++ b/doc/guides/contributing/abi_policy.rst
> @@ -159,6 +159,11 @@ The requirements for changing the ABI are:
>       ``experimental``, as described in the section on :ref:`Experimental APIs
>       and Libraries <experimental_apis>`.
>  
> +   - In situations where an ``experimental`` API has been stable for some time.
> +     When promoting the API to become part of the next ABI version, the
> +     maintainer may choose to provide an alias to the ``experimental`` tag, so
> +     as not to break consuming applications.
> +
I don't have any issue with the approach, but just to ask the question, is it
worth providing an example here, of how exactly to do this?  The use of
VERSION_SYMBOL isn't often used, and so may be non-obvious.

Actually, as I look at it, the VERSION_SYMBOL macro assume a DPDK_ prefix on the
version string, which works for versioned symbols, but not for the EXPERIMENTAL
symbol version (no DPDK_ prefix).  We should probably create a variant of the
VERSION_SYMBOL macro to allow aliasing to the EXPERIMENTAL version, something
like ALIAS_TO_EXPERIMENTAL() or some such

Neil

>  #. If a newly proposed API functionally replaces an existing one, when the new
>     API becomes non-experimental, then the old one is marked with
>     ``__rte_deprecated``.
> @@ -317,6 +322,11 @@ not required. Though, an API should remain in experimental state for at least
>  one release. Thereafter, the normal process of posting patch for review to
>  mailing list can be followed.
>  
> +After the experimental tag has been formally removed, a tree/sub-tree maintainer
> +may choose to offer an alias to the experimental tag so as not to break
> +applications using the API. This alias can then be dropped at the declaration of
> +next major ABI version.
> +
>  Libraries
>  ~~~~~~~~~
>  
> -- 
> 2.7.4
> 
> 

  parent reply	other threads:[~2020-02-25 15:35 UTC|newest]

Thread overview: 9+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-02-05 15:17 Ray Kinsella
2020-02-05 15:43 ` [dpdk-dev] [PATCH v3] " Ray Kinsella
2020-02-18 10:46 ` [dpdk-dev] [PATCH v4] " Ray Kinsella
2020-02-21 17:11   ` Ferruh Yigit
2020-02-25 14:22   ` Kevin Traynor
2020-02-25 15:35 ` Neil Horman [this message]
2020-02-25 17:57   ` [dpdk-dev] [PATCH] " David Marchand
2020-05-14 13:38 ` [dpdk-dev] [PATCH v5] " Ray Kinsella
2020-05-14 16:31   ` David Marchand

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200225153540.GA375824@hmswarspite.think-freely.org \
    --to=nhorman@tuxdriver.com \
    --cc=dev@dpdk.org \
    --cc=ferruh.yigit@intel.com \
    --cc=john.mcnamara@intel.com \
    --cc=marko.kovacevic@intel.co \
    --cc=mdr@ashroe.eu \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

DPDK patches and discussions

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://inbox.dpdk.org/dev/0 dev/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 dev dev/ https://inbox.dpdk.org/dev \
		dev@dpdk.org
	public-inbox-index dev

Example config snippet for mirrors.
Newsgroup available over NNTP:
	nntp://inbox.dpdk.org/inbox.dpdk.dev


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git