From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <luca.boccassi@gmail.com>
Received: from mail-wr0-f180.google.com (mail-wr0-f180.google.com
 [209.85.128.180]) by dpdk.org (Postfix) with ESMTP id D83F7160
 for <dev@dpdk.org>; Sat, 30 Dec 2017 20:21:00 +0100 (CET)
Received: by mail-wr0-f180.google.com with SMTP id v21so33261242wrc.0
 for <dev@dpdk.org>; Sat, 30 Dec 2017 11:21:00 -0800 (PST)
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=1e100.net; s=20161025;
 h=x-gm-message-state:message-id:subject:from:to:date:in-reply-to
 :references:content-transfer-encoding:mime-version;
 bh=A7cljntr0M7/PIcuGVBvCQymC2I4t/sKLHeX5kC9MxU=;
 b=MGi6l45x1+5vmQEZC2JizkMkQhVxxOeitkKrtpYhQ263GqkyCSKzmCALM6ONUmgZY8
 HCofOl+wrmdSETV866CdXCXaHG3SM6r8XgQpB12U3dWBpWA22SUcNI8QuqfCa6I0VoYu
 nLvpPWe6dmQzKriWZIFZknppjliUdSbRBMoiBkMr+Atms7t4qPey7ykxlkYWPZFark1f
 6wD34MfZhskwSPcUU90YVLx5qiDtueFZSdvZ51Xuqo9fbfSzMLD7xvcv0no45UWx72ox
 hXf+jC2vgH1W/gm9siGNdZ/Nw8QMffPXg+zbPAN1V/ciOvKCDCLkvjBba1rNudIGNTix
 mi1w==
X-Gm-Message-State: AKGB3mIbQgvre+5aU2xzGeivVleVvj3WNYkHP4AhDjl+aqMho9AANXxg
 yPgn1vnkSoN+V/2qAwNO9eAIUM6Tb7Y=
X-Google-Smtp-Source: ACJfBouKUSLRkGUD24b2LlDgMmzJsHOhBSyXiFwnJ/DIWAx11PH28kNVjsBd8t8WkHEZcBIEbXmmjA==
X-Received: by 10.223.148.225 with SMTP id 88mr34333780wrr.16.1514661660451;
 Sat, 30 Dec 2017 11:21:00 -0800 (PST)
Received: from localhost ([80.120.231.178])
 by smtp.gmail.com with ESMTPSA id u54sm9039839wrf.77.2017.12.30.11.20.59
 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256);
 Sat, 30 Dec 2017 11:20:59 -0800 (PST)
Message-ID: <1514661658.6638.59.camel@debian.org>
From: Luca Boccassi <bluca@debian.org>
To: Neil Horman <nhorman@tuxdriver.com>, dev@dpdk.org
Date: Sat, 30 Dec 2017 20:20:58 +0100
In-Reply-To: <20171213151728.16747-1-nhorman@tuxdriver.com>
References: <20171201185628.16261-1-nhorman@tuxdriver.com>
 <20171213151728.16747-1-nhorman@tuxdriver.com>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
X-Mailer: Evolution 3.22.6-1+deb9u1 
Mime-Version: 1.0
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: <https://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: <https://dpdk.org/ml/listinfo/dev>,
 <mailto:dev-request@dpdk.org?subject=subscribe>
X-List-Received-Date: Sat, 30 Dec 2017 19:21:01 -0000

On Wed, 2017-12-13 at 10:17 -0500, Neil Horman wrote:
> Hey all-
> =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0A few days ago, I was lam=
enting 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.=C2=A0=C2=A0John M. as=
ked me
> then what
> I might do to improve the situation, and the following patch set is a
> proposal
> that I've come up with.
>=20
> =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0In thinking about the pro=
blem I identified two issues that I
> think we
> can improve on in this area:
>=20
> 1) Make experimental api calls more visible in the source code.=C2=A0=C2=
=A0That
> 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
>=20
> 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.=C2=A0=C2=A0We make an effort to document all the experimenta=
l
> API's, but
> there is no guarantee that a user will check the documentation before
> making use
> of a new library.
>=20
> This patch set attempts to achieve both of the above goals.=C2=A0=C2=A0To=
 do
> this I've
> added an __experimental macro tag, suitable for inserting into api
> forward
> declarations and definitions.
>=20
> 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.
>=20
> 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.=C2=A0=C2=A0Developers can then make an informed decisio=
n to
> suppress
> that warning or not.
>=20
> 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.=C2=A0=C2=A0I 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.
>=20
> Neil
>=20
> ---
> 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
> =C2=A0 warnings/errors without need
>=20
> v3)
> * On suggestion from Bruce, modify ALLOW_EXPERIMENTAL_APIS to be
> defined in
> =C2=A0 CFLAGS rather than a makefile variable.=C2=A0=C2=A0This is more fl=
exible in
> that it
> =C2=A0 allows us to suppress this specific feature rather than all uses o=
f
> the
> =C2=A0 deprecated attribute, as we might use it for other features in the
> furute
>=20
> v4)
> * Added documentation patch to contributors guide

Acked-by: Luca Boccassi <bluca@debian.org>

I really like the idea of showing warnings at build time for users of
the libraries, in fact I like it so much I'm going to shamelessly steal
it for another few projects I work on where we have an experimental
(DRAFT) api system :-)

--=20
Kind regards,
Luca Boccassi