[dpdk-dev] [PATCH] doc: update ABI/API policy

[dpdk-dev] [PATCH] doc: update ABI/API policy

[Bruce Richardson]

Following agreement at the DPDK Technical Board meeting of 2017-10-13 [1],
update the documentation with the ABI/API policy changes.

[1] http://dpdk.org/ml/archives/dev/2017-October/079961.html

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/contributing/versioning.rst | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/doc/guides/contributing/versioning.rst b/doc/guides/contributing/versioning.rst
index 8d0fdb777..a1d8492a1 100644
--- a/doc/guides/contributing/versioning.rst
+++ b/doc/guides/contributing/versioning.rst
@@ -13,7 +13,9 @@ General Guidelines
 ------------------
 
 #. Whenever possible, ABI should be preserved
-#. The libraries marked in experimental state may change without constraint.
+#. Libraries or APIs marked in ``experimental`` state may change without constraint.
+#. New API will be marked as ``experimental`` for at least one release to allow
+   any issues found by users of the new API to be fixed quickly
 #. The addition of symbols is generally not problematic
 #. The modification of symbols can generally be managed with versioning
 #. The removal of symbols generally is an ABI break and requires bumping of the
@@ -41,6 +43,13 @@ ABI versions are set at the time of major release labeling, and the ABI may
 change multiple times, without warning, between the last release label and the
 HEAD label of the git tree.
 
+APIs marked as ``experimental`` are not considered part of the ABI and may
+change without warning at any time.  Since changes to APIs are most likely
+immediately after their introduction, as users begin to take advantage of
+those new API 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.
+
 ABI versions, once released, are available until such time as their
 deprecation has been noted in the Release Notes for at least one major release
 cycle. For example consider the case where the ABI for DPDK 2.0 has been
@@ -58,6 +67,14 @@ being provided. The requirements for doing so are:
 #. At least 3 acknowledgments of the need to do so must be made on the
    dpdk.org mailing list.
 
+   - The acknowledgment of the maintainer of the component is mandatory, or if
+     no maintainer is available for the component, the tree/sub-tree maintainer
+     for that component must be acknowledge the ABI change instead.
+
+   - It is also recommended that acknowledgments from different "areas of
+     interest" be sought for each deprecation, for example: from NIC vendors,
+     CPU vendors, end-users, etc.
+
 #. The changes (including an alternative map file) must be gated with
    the ``RTE_NEXT_ABI`` option, and provided with a deprecation notice at the
    same time.
-- 
2.13.6

Re: [dpdk-dev] [PATCH] doc: update ABI/API policy

[Mcnamara, John]

> -----Original Message-----
> From: Richardson, Bruce
> Sent: Monday, November 6, 2017 11:28 AM
> To: Mcnamara, John <john.mcnamara@intel.com>
> Cc: dev@dpdk.org; Richardson, Bruce <bruce.richardson@intel.com>
> Subject: [PATCH] doc: update ABI/API policy
> 
> Following agreement at the DPDK Technical Board meeting of 2017-10-13 [1],
> update the documentation with the ABI/API policy changes.
> 
> [1] http://dpdk.org/ml/archives/dev/2017-October/079961.html
> 
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> ---
>  doc/guides/contributing/versioning.rst | 19 ++++++++++++++++++-
>  1 file changed, 18 insertions(+), 1 deletion(-)
> 
> diff --git a/doc/guides/contributing/versioning.rst
> b/doc/guides/contributing/versioning.rst
> index 8d0fdb777..a1d8492a1 100644
> --- a/doc/guides/contributing/versioning.rst
> +++ b/doc/guides/contributing/versioning.rst
> @@ -13,7 +13,9 @@ General Guidelines
>  ------------------
> 
>  #. Whenever possible, ABI should be preserved -#. The libraries marked in
> experimental state may change without constraint.
> +#. Libraries or APIs marked in ``experimental`` state may change without
> constraint.
> +#. New API will be marked as ``experimental`` for at least one release to

s/API/APIs/


> +APIs marked as ``experimental`` are not considered part of the ABI and
> +may change without warning at any time.  Since changes to APIs are most
> +likely immediately after their introduction, as users begin to take
> +advantage of those new API and start finding issues with them, new DPDK

s/API/APIs/


> +   - The acknowledgment of the maintainer of the component is mandatory, or if
> +     no maintainer is available for the component, the tree/sub-tree maintainer
> +     for that component must be acknowledge the ABI change instead.

s/must be/must/

Apart from that:

Acked-by: John McNamara <john.mcnamara@intel.com>

Re: [dpdk-dev] [PATCH] doc: update ABI/API policy

[Yuanhan Liu]

On Mon, Nov 06, 2017 at 11:28:06AM +0000, Bruce Richardson wrote:
> Following agreement at the DPDK Technical Board meeting of 2017-10-13 [1],
> update the documentation with the ABI/API policy changes.
> 
> [1] http://dpdk.org/ml/archives/dev/2017-October/079961.html
> 
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>

Acked-by: Yuanhan Liu <yliu@fridaylinux.org>

	--yliu

Re: [dpdk-dev] [PATCH] doc: update ABI/API policy

[Kevin Traynor]

On 11/06/2017 11:28 AM, Bruce Richardson wrote:
> Following agreement at the DPDK Technical Board meeting of 2017-10-13 [1],
> update the documentation with the ABI/API policy changes.
> 
> [1] http://dpdk.org/ml/archives/dev/2017-October/079961.html
> 
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>

Acked-by: Kevin Traynor <ktraynor@redhat.com>

Re: [dpdk-dev] [PATCH] doc: update ABI/API policy

[Thomas Monjalon]

06/11/2017 15:48, Mcnamara, John:
> From: Richardson, Bruce
> > 
> > Following agreement at the DPDK Technical Board meeting of 2017-10-13 [1],
> > update the documentation with the ABI/API policy changes.
> > 
> > [1] http://dpdk.org/ml/archives/dev/2017-October/079961.html
> > 
> > Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> > ---
> >  doc/guides/contributing/versioning.rst | 19 ++++++++++++++++++-
> >  1 file changed, 18 insertions(+), 1 deletion(-)
> > 
> > diff --git a/doc/guides/contributing/versioning.rst
> > b/doc/guides/contributing/versioning.rst
> > index 8d0fdb777..a1d8492a1 100644
> > --- a/doc/guides/contributing/versioning.rst
> > +++ b/doc/guides/contributing/versioning.rst
> > @@ -13,7 +13,9 @@ General Guidelines
> >  ------------------
> > 
> >  #. Whenever possible, ABI should be preserved -#. The libraries marked in
> > experimental state may change without constraint.
> > +#. Libraries or APIs marked in ``experimental`` state may change without
> > constraint.
> > +#. New API will be marked as ``experimental`` for at least one release to
> 
> s/API/APIs/
> 
> 
> > +APIs marked as ``experimental`` are not considered part of the ABI and
> > +may change without warning at any time.  Since changes to APIs are most
> > +likely immediately after their introduction, as users begin to take
> > +advantage of those new API and start finding issues with them, new DPDK
> 
> s/API/APIs/
> 
> 
> > +   - The acknowledgment of the maintainer of the component is mandatory, or if
> > +     no maintainer is available for the component, the tree/sub-tree maintainer
> > +     for that component must be acknowledge the ABI change instead.
> 
> s/must be/must/
> 
> Apart from that:
> 
> Acked-by: John McNamara <john.mcnamara@intel.com>

Acked-by: Thomas Monjalon <thomas@monjalon.net>

Applied with suggested changes, thanks