From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: <dev-bounces@dpdk.org> Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id 5B72CA055B; Tue, 25 Feb 2020 18:57:54 +0100 (CET) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 712601BFAB; Tue, 25 Feb 2020 18:57:53 +0100 (CET) Received: from us-smtp-delivery-1.mimecast.com (us-smtp-1.mimecast.com [205.139.110.61]) by dpdk.org (Postfix) with ESMTP id C79833B5 for <dev@dpdk.org>; Tue, 25 Feb 2020 18:57:51 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1582653471; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=iQSlSU902xMIkSH4lKrLcVta2wl77jQzD8sLk4Pz+Xc=; b=I0DWyGSkSOFXWL+Tsqkb9+YRH481UetAet87OMJ7Cwn4g5iWzzAiwVKLF2dAPuims9DWhe gZCxQ/HcS24qLK6siMSUSXR0f5qlztpNoJB7aj/DG3y+AuI9oZaUSTiAijLvwGLeGsjhvv q5RCxmhT80s2uC2QOoJqRRX2uvkuKAM= Received: from mail-il1-f197.google.com (mail-il1-f197.google.com [209.85.166.197]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-236-TAoaBzuNMdSiaWHDiYpXgw-1; Tue, 25 Feb 2020 12:57:47 -0500 X-MC-Unique: TAoaBzuNMdSiaWHDiYpXgw-1 Received: by mail-il1-f197.google.com with SMTP id d3so26400205ilg.20 for <dev@dpdk.org>; Tue, 25 Feb 2020 09:57:47 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=X2AJ5lar4x8DVEho/35UMW6wZ2ePjE+cUkryzZzXTQ0=; b=YG+GEXjYtPpPskovHV/YFRD2+Mr0udn6qcFLyzPWsFcsLrfh/SnipVdI/3jLMGhpcx byHyzLHQKt3xVkxQpq9vt9LCKL911uztQS20j9g9WAUl/0q2C6do42gLzZdX8tdj5DPS y1qs8c77JtpGzlLRkMNaITYUCz0l/IfIPd89GO/8NPm/rhl1bDDJUArOZUMm8jTp3H13 yBdU/ideXm9rN6iCbFl1rddXxuAFuSGogjxV9pUEn12ATBzliSnSIkMa91wVSxEAhMVF BCCxe14kfNmoUHqid8/PtPbUC04m0re08CGkQDEfQFVxRCS4/OoYIX8LYhsRTlevcD96 u9tA== X-Gm-Message-State: APjAAAWkTv8yXAXlFh9VgBgEcRqEN1BLIsvk49MKuXmTy8NIZTPqtJcj tv0OSDya1rHiCWD02+L9Q9mTi8doRwmjaV5wI2EOE+seocpWKzKAgCqgUQKWh9kBA3VIqRZqaY8 EkxtwCRwNPeHBf5Za/eo= X-Received: by 2002:a92:1547:: with SMTP id v68mr68984691ilk.58.1582653466559; Tue, 25 Feb 2020 09:57:46 -0800 (PST) X-Google-Smtp-Source: APXvYqyA6CEcNoa6mWh47cIgoX8yaMCYwQjHf+4oBygcddGFVusU7LWWrpKuvI7ceCqARINtAtQKXaeo9dCicICy53I= X-Received: by 2002:a92:1547:: with SMTP id v68mr68984676ilk.58.1582653466323; Tue, 25 Feb 2020 09:57:46 -0800 (PST) MIME-Version: 1.0 References: <1580915872-1686-1-git-send-email-mdr@ashroe.eu> <20200225153540.GA375824@hmswarspite.think-freely.org> In-Reply-To: <20200225153540.GA375824@hmswarspite.think-freely.org> From: David Marchand <david.marchand@redhat.com> Date: Tue, 25 Feb 2020 18:57:35 +0100 Message-ID: <CAJFAV8xq2HQ_yyGEXhkApUJAfJ9XTExgStA0mtTTSfCUmnkquQ@mail.gmail.com> To: Ray Kinsella <mdr@ashroe.eu>, Neil Horman <nhorman@tuxdriver.com> Cc: dev <dev@dpdk.org>, "Mcnamara, John" <john.mcnamara@intel.com>, "Yigit, Ferruh" <ferruh.yigit@intel.com>, "Kovacevic, Marko" <marko.kovacevic@intel.co> X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Subject: Re: [dpdk-dev] [PATCH] doc: alias to experimental tag for stable apis 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://mails.dpdk.org/options/dev>, <mailto:dev-request@dpdk.org?subject=unsubscribe> List-Archive: <http://mails.dpdk.org/archives/dev/> List-Post: <mailto:dev@dpdk.org> List-Help: <mailto:dev-request@dpdk.org?subject=help> List-Subscribe: <https://mails.dpdk.org/listinfo/dev>, <mailto:dev-request@dpdk.org?subject=subscribe> Errors-To: dev-bounces@dpdk.org Sender: "dev" <dev-bounces@dpdk.org> On Tue, Feb 25, 2020 at 4:36 PM Neil Horman <nhorman@tuxdriver.com> wrote: > > 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 ad= vance of > > the declaration of the next ABI version. The maintainer may choose to o= ffer an > > alias to the experimental tag, as removing the tag before the declarati= on of the > > next major ABI version, would cause an ABI breakage for applications us= ing 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/contri= buting/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:`Experiment= al APIs > > and Libraries <experimental_apis>`. > > > > + - In situations where an ``experimental`` API has been stable for s= ome time. > > + When promoting the API to become part of the next ABI version, th= e > > + 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, i= s 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 EXPERI= MENTAL > symbol version (no DPDK_ prefix). We should probably create a variant of= the > VERSION_SYMBOL macro to allow aliasing to the EXPERIMENTAL version, somet= hing > like ALIAS_TO_EXPERIMENTAL() or some such Let's clarify this part so this can be merged in early 20.05. Thanks. --=20 David Marchand