From: Neil Horman <nhorman@tuxdriver.com>
To: Ferruh Yigit <ferruh.yigit@intel.com>
Cc: dev@dpdk.org, thomas@monjalon.net, john.mcnamara@intel.com,
bruce.richardson@intel.com
Subject: Re: [dpdk-dev] [PATCHv4 5/5] doc: Add ABI __experimental tag documentation
Date: Fri, 12 Jan 2018 19:28:40 -0500 [thread overview]
Message-ID: <20180113002840.GA17575@neilslaptop.think-freely.org> (raw)
In-Reply-To: <2ba5be68-4d5d-9f37-e86a-fe23b6708056@intel.com>
On Fri, Jan 12, 2018 at 03:55:10PM +0000, Ferruh Yigit wrote:
> On 1/12/2018 2:37 PM, Neil Horman wrote:
> > On Fri, Jan 12, 2018 at 11:50:12AM +0000, Ferruh Yigit wrote:
> >> On 1/11/2018 9:29 PM, Neil Horman wrote:
> >>> On Thu, Jan 11, 2018 at 08:06:48PM +0000, Ferruh Yigit wrote:
> >>>> On 12/13/2017 3:17 PM, Neil Horman wrote:
> >>>>> Document the need to add the __experimental tag to appropriate functions
> >>>>>
> >>>>> Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
> >>>>> CC: Thomas Monjalon <thomas@monjalon.net>
> >>>>> CC: "Mcnamara, John" <john.mcnamara@intel.com>
> >>>>> CC: Bruce Richardson <bruce.richardson@intel.com>
> >>
> >> <...>
> >>
> >>>>> automatically marked as ``experimental`` to allow for a period of stabilization>>> before they become part of a tracked ABI.
> >>
> >> Full sentences for above statement:
> >> "
> >> Since changes to APIs are most likely immediately after their introduction, as
> >> users begin to take advantage of those new APIs and start finding issues with
> >> them, new DPDK APIs will be automatically marked as experimental to allow for a
> >> period of stabilization before they become part of a tracked ABI.
> >> "
> >>
> >> This part is not related to this patchset, but it will be hard to maintain above
> >> behavior, "automatically marked" is not automatic now and moving them to stable
> >> after one release is also not automatic. Do you have any suggestion on how to
> >> manage this, do you think can your script be expanded to cover these checks?
> >>
> >
> > I would make the argument that this was never the case, but rather a statement
> > of principle. I assert that because I can find no mechanism anywhere in our
> > build system that 'automatically' documented or marked a new API as experimental
> > (please correct me if I'm wrong here). I think this was more meant to be a
> > directive to developers to do whatever coding was needed to preform such
> > marking/documentation in whatever style/format was current. E.g. introducers of
> > a new API should document everything as EXPERIMENTAL using the appropriate
> > doxygen tag and version map tag.
> >
> > In answer to your question, While we might be able to expand my script to check
> > for new API's and ensure they are marked as experimental, I don't think thats
> > the right place to do it, because that script is run at build time, where the
> > state of the tree is transient. A better place to do it would be with a git hook
> > at checkin time, or in the checkpatch script to flag new apis as experimental
> > right before those new API's are comitted. Though I'm not a huge fan of that
> > either (at least not of the former suggestion). I say that because I think we
> > need to allow developers the freedom to determine the supported status of any
> > new API that they add. For example, it seems pretty clear that a new library
> > might want to have its entire API marked as experimental, but someone adding a
> > single new function to an existing API might be confident that the new function
> > is needed and should be immediately supported..
> >
> > I think the better solution is to define the use of the EXPERIMENTAL tag in the
> > version map as the canonical location to define unstable API functions. Doing
> > so immediately commits an author to ensuring that the corresponding function
> > definitions are marked with the __experimental tags, which in turn will cause
> > any downstream users to be alerted to the fact that they might be using those
> > API's in their code, so they can take appropriate action. It still allows for
> > the Documentation to be out of sync, but alerting authors doing development I
> > think is the more important element here, as Documentation can be corrected more
> > easily than code in the field.
> >
> > Thoughts?
>
> After this point agree to using EXPERIMENTAL tag in the version map as standard,
> but it will be hard to maintain "API is experimental for first release" without
> help of any automated tool.
>
I completely agree, in fact I would say it is impossible to do without tooling,
with or without this change. I think we need to do 1 of 2 things:
1) Add some code to checkpatch.pl to put up a warning if any new apis are added
without marking them as experimental
2) Change the documentation to be a suggestion rather than a requirement.
I'll look into doing (1), but I'm wondering if (2) is the more flexible way to
go. I'm hesitant to enforce the initial marking of new APIs as experimental.
Thoughts?
Neil
next prev parent reply other threads:[~2018-01-13 0:28 UTC|newest]
Thread overview: 83+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-12-01 18:56 [dpdk-dev] [PATCH 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
2017-12-01 18:56 ` [dpdk-dev] [PATCH 1/4] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
2017-12-01 18:56 ` [dpdk-dev] [PATCH 2/4] compat: Add __experimental macro Neil Horman
2017-12-01 18:56 ` [dpdk-dev] [PATCH 3/4] dpdk: add __experimental tag to appropriate api calls Neil Horman
2017-12-01 18:56 ` [dpdk-dev] [PATCH 4/4] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
2017-12-08 17:14 ` [dpdk-dev] [PATCHv2 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
2017-12-08 17:14 ` [dpdk-dev] [PATCHv2 1/4] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
2017-12-08 17:14 ` [dpdk-dev] [PATCHv2 2/4] compat: Add __experimental macro Neil Horman
2017-12-08 17:14 ` [dpdk-dev] [PATCHv2 3/4] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
2017-12-11 11:35 ` Bruce Richardson
2017-12-11 12:40 ` Neil Horman
2017-12-11 12:45 ` Bruce Richardson
2017-12-11 18:44 ` Neil Horman
2017-12-08 17:14 ` [dpdk-dev] [PATCHv2 4/4] dpdk: add __experimental tag to appropriate api calls Neil Horman
2017-12-11 19:36 ` [dpdk-dev] [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
2017-12-11 19:36 ` [dpdk-dev] [PATCHv3 1/4] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
2017-12-11 19:36 ` [dpdk-dev] [PATCHv3 2/4] compat: Add __experimental macro Neil Horman
2017-12-11 19:36 ` [dpdk-dev] [PATCHv3 3/4] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
2017-12-11 19:36 ` [dpdk-dev] [PATCHv3 4/4] dpdk: add __experimental tag to appropriate api calls Neil Horman
2017-12-12 14:07 ` [dpdk-dev] [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging Bruce Richardson
2017-12-30 17:15 ` Neil Horman
2018-01-04 12:56 ` Neil Horman
2018-01-05 14:08 ` Thomas Monjalon
2018-01-05 16:00 ` Neil Horman
2018-01-09 1:32 ` [dpdk-dev] [dpdk-ci] " Neil Horman
2018-01-09 9:20 ` Thomas Monjalon
2018-01-09 12:36 ` Neil Horman
2018-01-19 15:44 ` Neil Horman
2017-12-12 14:33 ` [dpdk-dev] " Mcnamara, John
2017-12-12 20:18 ` Neil Horman
2017-12-12 15:11 ` Wiles, Keith
2017-12-12 20:14 ` Neil Horman
2017-12-13 15:17 ` [dpdk-dev] [PATCHv4 " Neil Horman
2017-12-13 15:17 ` [dpdk-dev] [PATCHv4 1/5] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
2018-01-21 18:31 ` Thomas Monjalon
2018-01-21 22:07 ` Neil Horman
2017-12-13 15:17 ` [dpdk-dev] [PATCHv4 2/5] compat: Add __experimental macro Neil Horman
2018-01-21 18:37 ` Thomas Monjalon
2017-12-13 15:17 ` [dpdk-dev] [PATCHv4 3/5] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
2018-01-11 20:06 ` Ferruh Yigit
2018-01-11 20:50 ` Neil Horman
2018-01-12 11:49 ` Ferruh Yigit
2018-01-12 12:44 ` Neil Horman
2018-01-21 18:54 ` Thomas Monjalon
2018-01-22 1:34 ` Neil Horman
2018-01-22 1:37 ` Thomas Monjalon
2018-01-21 18:50 ` Thomas Monjalon
2018-01-22 1:19 ` Neil Horman
2017-12-13 15:17 ` [dpdk-dev] [PATCHv4 4/5] dpdk: add __experimental tag to appropriate api calls Neil Horman
2018-01-11 20:06 ` Ferruh Yigit
2018-01-11 21:24 ` Neil Horman
2018-01-12 11:50 ` Ferruh Yigit
2018-01-12 14:25 ` Neil Horman
2018-01-12 15:53 ` Ferruh Yigit
2017-12-13 15:17 ` [dpdk-dev] [PATCHv4 5/5] doc: Add ABI __experimental tag documentation Neil Horman
2017-12-13 15:32 ` Bruce Richardson
2018-01-11 20:06 ` Ferruh Yigit
2018-01-11 21:29 ` Neil Horman
2018-01-12 11:50 ` Ferruh Yigit
2018-01-12 14:37 ` Neil Horman
2018-01-12 15:55 ` Ferruh Yigit
2018-01-13 0:28 ` Neil Horman [this message]
2018-01-13 15:56 ` Thomas Monjalon
2018-01-14 14:36 ` Neil Horman
2018-01-14 16:27 ` Thomas Monjalon
2018-01-21 20:14 ` Thomas Monjalon
2017-12-13 15:32 ` [dpdk-dev] [PATCHv4 0/4] dpdk: enhance EXPERIMENTAL api tagging Bruce Richardson
2017-12-21 14:21 ` Neil Horman
2017-12-30 19:20 ` Luca Boccassi
2017-12-31 1:57 ` Neil Horman
2018-01-22 1:48 ` [dpdk-dev] [PATCH 0/5] " Neil Horman
2018-01-22 1:48 ` [dpdk-dev] [[PATCH v5] 1/5] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
2018-01-22 1:48 ` [dpdk-dev] [[PATCH v5] 2/5] compat: Add __rte_experimental macro Neil Horman
2018-01-22 1:48 ` [dpdk-dev] [[PATCH v5] 3/5] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
2018-01-22 1:48 ` [dpdk-dev] [[PATCH v5] 4/5] dpdk: add __rte_experimental tag to appropriate api calls Neil Horman
2018-01-22 1:48 ` [dpdk-dev] [[PATCH v5] 5/5] doc: Add ABI __experimental tag documentation Neil Horman
2018-01-23 10:35 ` Mcnamara, John
2018-01-29 21:42 ` Thomas Monjalon
2018-01-29 21:46 ` [dpdk-dev] [PATCH 0/5] dpdk: enhance EXPERIMENTAL api tagging Thomas Monjalon
2018-01-30 15:54 ` Neil Horman
2018-01-30 16:15 ` Thomas Monjalon
2018-01-31 12:18 ` Neil Horman
2018-01-31 12:36 ` Thomas Monjalon
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=20180113002840.GA17575@neilslaptop.think-freely.org \
--to=nhorman@tuxdriver.com \
--cc=bruce.richardson@intel.com \
--cc=dev@dpdk.org \
--cc=ferruh.yigit@intel.com \
--cc=john.mcnamara@intel.com \
--cc=thomas@monjalon.net \
/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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).