From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <bruce.richardson@intel.com>
Received: from mga05.intel.com (mga05.intel.com [192.55.52.43])
 by dpdk.org (Postfix) with ESMTP id E117D271
 for <dev@dpdk.org>; Wed, 13 Dec 2017 16:32:42 +0100 (CET)
X-Amp-Result: UNKNOWN
X-Amp-Original-Verdict: FILE UNKNOWN
X-Amp-File-Uploaded: False
Received: from fmsmga002.fm.intel.com ([10.253.24.26])
 by fmsmga105.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384;
 13 Dec 2017 07:32:41 -0800
X-ExtLoop1: 1
X-IronPort-AV: E=Sophos;i="5.45,397,1508828400"; 
   d="scan'208";a="1278791"
Received: from bricha3-mobl3.ger.corp.intel.com ([10.237.221.106])
 by fmsmga002.fm.intel.com with SMTP; 13 Dec 2017 07:32:39 -0800
Received: by  (sSMTP sendmail emulation); Wed, 13 Dec 2017 15:32:39 +0000
Date: Wed, 13 Dec 2017 15:32:38 +0000
From: Bruce Richardson <bruce.richardson@intel.com>
To: Neil Horman <nhorman@tuxdriver.com>
Cc: dev@dpdk.org, thomas@monjalon.net, john.mcnamara@intel.com
Message-ID: <20171213153238.GB12256@bricha3-MOBL3.ger.corp.intel.com>
References: <20171201185628.16261-1-nhorman@tuxdriver.com>
 <20171213151728.16747-1-nhorman@tuxdriver.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20171213151728.16747-1-nhorman@tuxdriver.com>
Organization: Intel Research and Development Ireland Ltd.
User-Agent: Mutt/1.9.1 (2017-09-22)
Subject: Re: [dpdk-dev] [PATCHv4 0/4] dpdk: enhance EXPERIMENTAL api tagging
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <http://dpdk.org/ml/options/dev>,
 <mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://dpdk.org/ml/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <http://dpdk.org/ml/listinfo/dev>,
 <mailto:dev-request@dpdk.org?subject=subscribe>
X-List-Received-Date: Wed, 13 Dec 2017 15:32:43 -0000

On Wed, Dec 13, 2017 at 10:17:23AM -0500, Neil Horman wrote:
> Hey all-
>         A few days ago, I was lamenting the fact that, when reviewing patches I
> would frequently complain about ABI changes that were actually considered safe
> because they were part of the EXPERIMENTAL api set.  John M. asked me then what
> I might do to improve the situation, and the following patch set is a proposal
> that I've come up with.
> 
>         In thinking about the problem I identified two issues that I think we
> can improve on in this area:
> 
> 1) Make experimental api calls more visible in the source code.  That is to say,
> when reviewing patches, it would be nice to have some sort of visual reference
> that indicates that the changes being made are part of an experimental API and
> therefore ABI concerns need not be addressed
> 
> 2) Make experimenal api usage more visible to consumers of the DPDK, so that
> they can make a more informed decision about the API's they consume in their
> application.  We make an effort to document all the experimental API's, but
> there is no guarantee that a user will check the documentation before making use
> of a new library.
> 
> This patch set attempts to achieve both of the above goals.  To do this I've
> added an __experimental macro tag, suitable for inserting into api forward
> declarations and definitions.
> 
> The presence of the tag in the header and c files where the api code resides
> increases the likelyhood that any patch submitted against them will include the
> tag in the context, making it clear to reviewers that ABI stability isn't a
> concern here.
> 
> Also, This tag marks each function it is used on with an attibute causing any
> use of the fuction to emit a warning during the build
> with a message indicating that the API call in question is not yet part of the
> stable interface.  Developers can then make an informed decision to suppress
> that warning or not.
> 
> Because there is internal use of several experimental API's, this set also
> includes a new override macro ALLOW_EXPERIMENTAL_APIS to automatically
> suprress these warnings.  I think its fair to assume that, for internal use, we
> almost always want to suppress these warnings, as by definition any change to
> the apis (even their removal) must be done in parallel with an appropriate
> change in the calling locations, lest the dpdk build itself break.
> 
> Neil
> 
> ---
> Change Notes:
> v2)
> * Cleaned up checkpatch errors
> * Added Allowance for building experimental on BSD
> * Swapped Patch 3 and 4 so that we didn't have a commit level that issued
>   warnings/errors without need
> 
> v3)
> * On suggestion from Bruce, modify ALLOW_EXPERIMENTAL_APIS to be defined in
>   CFLAGS rather than a makefile variable.  This is more flexible in that it
>   allows us to suppress this specific feature rather than all uses of the
>   deprecated attribute, as we might use it for other features in the furute
> 
> v4)
> * Added documentation patch to contributors guide
> 

Series Acked-by: Bruce Richardson <bruce.richardson@intel.com>