[dpdk-dev] [PATCH v1 0/2] doc: minor abi policy fixes

[dpdk-dev] [PATCH v1 0/2] doc: minor abi policy fixes

[Ray Kinsella]

Few documentation fixexs, clarifing the Windows ABI policy and aliases to
experimental mode.

Ray Kinsella (2):
  doc: reword abi policy for windows
  doc: clarify alias to experimental period

 doc/guides/contributing/abi_policy.rst     | 4 +++-
 doc/guides/contributing/abi_versioning.rst | 7 ++++---
 doc/guides/windows_gsg/intro.rst           | 6 +++---
 3 files changed, 10 insertions(+), 7 deletions(-)

--
2.7.4

[dpdk-dev] [PATCH v1 1/2] doc: reword abi policy for windows

[Ray Kinsella]

Minor changes to the abi policy for windows.

Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
---
 doc/guides/contributing/abi_policy.rst | 4 +++-
 doc/guides/windows_gsg/intro.rst       | 6 +++---
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
index d0affa9..8e70b45 100644
--- a/doc/guides/contributing/abi_policy.rst
+++ b/doc/guides/contributing/abi_policy.rst
@@ -40,7 +40,9 @@ General Guidelines
    maintaining ABI stability through one year of DPDK releases starting from
    DPDK 19.11. This policy will be reviewed in 2020, with intention of
    lengthening the stability period. Additional implementation detail can be
-   found in the :ref:`release notes <20_02_abi_changes>`.
+   found in the :ref:`release notes <20_02_abi_changes>`. Please note that this
+   policy does not currently apply to the :doc:`Window build
+   <../windows_gsg/intro>`.
 
 What is an ABI?
 ~~~~~~~~~~~~~~~
diff --git a/doc/guides/windows_gsg/intro.rst b/doc/guides/windows_gsg/intro.rst
index 58c6246..707afd3 100644
--- a/doc/guides/windows_gsg/intro.rst
+++ b/doc/guides/windows_gsg/intro.rst
@@ -19,6 +19,6 @@ compile. Support is being added in pieces so as to limit the overall scope
 of any individual patch series. The goal is to be able to run any DPDK
 application natively on Windows.
 
-The :doc:`../contributing/abi_policy` cannot be respected for Windows.
-Minor ABI versions may be incompatible
-because function versioning is not supported on Windows.
+The :doc:`../contributing/abi_policy` does not apply to the Windows build, as
+function versioning is not supported on Windows, therefore minor ABI versions
+may be incompatible.
-- 
2.7.4

[dpdk-dev] [PATCH v1 2/2] doc: clarify alias to experimental period

[Ray Kinsella]

Clarify retention period for aliases to experimental.

Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
---
 doc/guides/contributing/abi_versioning.rst | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/doc/guides/contributing/abi_versioning.rst b/doc/guides/contributing/abi_versioning.rst
index 31a9205..e00dfa8 100644
--- a/doc/guides/contributing/abi_versioning.rst
+++ b/doc/guides/contributing/abi_versioning.rst
@@ -158,7 +158,7 @@ The macros exported are:
 * ``VERSION_SYMBOL_EXPERIMENTAL(b, e)``: Creates a symbol version table entry
   binding versioned symbol ``b@EXPERIMENTAL`` to the internal function ``be``.
   The macro is used when a symbol matures to become part of the stable ABI, to
-  provide an alias to experimental for some time.
+  provide an alias to experimental until the next major ABI version.
 
 .. _example_abi_macro_usage:
 
@@ -428,8 +428,9 @@ _____________________________
 
 In situations in which an ``experimental`` symbol has been stable for some time,
 and it becomes a candidate for promotion to the stable ABI. At this time, when
-promoting the symbol, maintainer may choose to provide an alias to the
-``experimental`` symbol version, so as not to break consuming applications.
+promoting the symbol, the maintainer may choose to provide an alias to the
+``experimental`` symbol version, so as not to break consuming applications. This
+alias will then typically be dropped in the next major ABI version.
 
 The process to provide an alias to ``experimental`` is similar to that, of
 :ref:`symbol versioning <example_abi_macro_usage>` described above.
-- 
2.7.4

Re: [dpdk-dev] [PATCH v1 1/2] doc: reword abi policy for windows

[Thomas Monjalon]

07/07/2020 16:45, Ray Kinsella:
> Minor changes to the abi policy for windows.

It looks like you were not fast enough to comment
in the original thread :)
Please add a Fixes line to reference the original commit.

> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
> ---
>  doc/guides/contributing/abi_policy.rst | 4 +++-
>  doc/guides/windows_gsg/intro.rst       | 6 +++---
>  2 files changed, 6 insertions(+), 4 deletions(-)
> 
> diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
> index d0affa9..8e70b45 100644
> --- a/doc/guides/contributing/abi_policy.rst
> +++ b/doc/guides/contributing/abi_policy.rst
> @@ -40,7 +40,9 @@ General Guidelines
>     maintaining ABI stability through one year of DPDK releases starting from
>     DPDK 19.11. This policy will be reviewed in 2020, with intention of
>     lengthening the stability period. Additional implementation detail can be
> -   found in the :ref:`release notes <20_02_abi_changes>`.
> +   found in the :ref:`release notes <20_02_abi_changes>`. Please note that this
> +   policy does not currently apply to the :doc:`Window build

Window -> Windows

> +   <../windows_gsg/intro>`.
>  
>  What is an ABI?
>  ~~~~~~~~~~~~~~~
> diff --git a/doc/guides/windows_gsg/intro.rst b/doc/guides/windows_gsg/intro.rst
> index 58c6246..707afd3 100644
> --- a/doc/guides/windows_gsg/intro.rst
> +++ b/doc/guides/windows_gsg/intro.rst
> @@ -19,6 +19,6 @@ compile. Support is being added in pieces so as to limit the overall scope
>  of any individual patch series. The goal is to be able to run any DPDK
>  application natively on Windows.
>  
> -The :doc:`../contributing/abi_policy` cannot be respected for Windows.
> -Minor ABI versions may be incompatible
> -because function versioning is not supported on Windows.
> +The :doc:`../contributing/abi_policy` does not apply to the Windows build, as
> +function versioning is not supported on Windows, therefore minor ABI versions
> +may be incompatible.

Please I really prefer we split lines logically rather than filling the space:
The :doc:`../contributing/abi_policy` does not apply to the Windows build,
as function versioning is not supported on Windows,
therefore minor ABI versions may be incompatible.

Re: [dpdk-dev] [PATCH v1 2/2] doc: clarify alias to experimental period

[Thomas Monjalon]

07/07/2020 16:45, Ray Kinsella:
> Clarify retention period for aliases to experimental.
> 
> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
> ---
> --- a/doc/guides/contributing/abi_versioning.rst
> +++ b/doc/guides/contributing/abi_versioning.rst
> @@ -158,7 +158,7 @@ The macros exported are:
>  * ``VERSION_SYMBOL_EXPERIMENTAL(b, e)``: Creates a symbol version table entry
>    binding versioned symbol ``b@EXPERIMENTAL`` to the internal function ``be``.
>    The macro is used when a symbol matures to become part of the stable ABI, to
> -  provide an alias to experimental for some time.
> +  provide an alias to experimental until the next major ABI version.

Why limiting the period for experimental status?
Some API want to remain experimental longer.

[...]
>  In situations in which an ``experimental`` symbol has been stable for some time,
>  and it becomes a candidate for promotion to the stable ABI. At this time, when
> -promoting the symbol, maintainer may choose to provide an alias to the
> -``experimental`` symbol version, so as not to break consuming applications.
> +promoting the symbol, the maintainer may choose to provide an alias to the
> +``experimental`` symbol version, so as not to break consuming applications. This

Please start a sentence on a new line.

> +alias will then typically be dropped in the next major ABI version.

I don't see the need for the time estimation.

Re: [dpdk-dev] [PATCH v1 1/2] doc: reword abi policy for windows

[Kinsella, Ray]

On 07/07/2020 16:23, Thomas Monjalon wrote:
> 07/07/2020 16:45, Ray Kinsella:
>> Minor changes to the abi policy for windows.
> 
> It looks like you were not fast enough to comment
> in the original thread :)
> Please add a Fixes line to reference the original commit.
> 
>> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
>> ---
>>  doc/guides/contributing/abi_policy.rst | 4 +++-
>>  doc/guides/windows_gsg/intro.rst       | 6 +++---
>>  2 files changed, 6 insertions(+), 4 deletions(-)
>>
>> diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
>> index d0affa9..8e70b45 100644
>> --- a/doc/guides/contributing/abi_policy.rst
>> +++ b/doc/guides/contributing/abi_policy.rst
>> @@ -40,7 +40,9 @@ General Guidelines
>>     maintaining ABI stability through one year of DPDK releases starting from
>>     DPDK 19.11. This policy will be reviewed in 2020, with intention of
>>     lengthening the stability period. Additional implementation detail can be
>> -   found in the :ref:`release notes <20_02_abi_changes>`.
>> +   found in the :ref:`release notes <20_02_abi_changes>`. Please note that this
>> +   policy does not currently apply to the :doc:`Window build
> 
> Window -> Windows

ACK

> 
>> +   <../windows_gsg/intro>`.
>>  
>>  What is an ABI?
>>  ~~~~~~~~~~~~~~~
>> diff --git a/doc/guides/windows_gsg/intro.rst b/doc/guides/windows_gsg/intro.rst
>> index 58c6246..707afd3 100644
>> --- a/doc/guides/windows_gsg/intro.rst
>> +++ b/doc/guides/windows_gsg/intro.rst
>> @@ -19,6 +19,6 @@ compile. Support is being added in pieces so as to limit the overall scope
>>  of any individual patch series. The goal is to be able to run any DPDK
>>  application natively on Windows.
>>  
>> -The :doc:`../contributing/abi_policy` cannot be respected for Windows.
>> -Minor ABI versions may be incompatible
>> -because function versioning is not supported on Windows.
>> +The :doc:`../contributing/abi_policy` does not apply to the Windows build, as
>> +function versioning is not supported on Windows, therefore minor ABI versions
>> +may be incompatible.
> 
> Please I really prefer we split lines logically rather than filling the space:
> The :doc:`../contributing/abi_policy` does not apply to the Windows build,
> as function versioning is not supported on Windows,
> therefore minor ABI versions may be incompatible.
> 
That is a single line though :-)
 

Re: [dpdk-dev] [PATCH v1 2/2] doc: clarify alias to experimental period

[Kinsella, Ray]

On 07/07/2020 16:26, Thomas Monjalon wrote:
> 07/07/2020 16:45, Ray Kinsella:
>> Clarify retention period for aliases to experimental.
>>
>> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
>> ---
>> --- a/doc/guides/contributing/abi_versioning.rst
>> +++ b/doc/guides/contributing/abi_versioning.rst
>> @@ -158,7 +158,7 @@ The macros exported are:
>>  * ``VERSION_SYMBOL_EXPERIMENTAL(b, e)``: Creates a symbol version table entry
>>    binding versioned symbol ``b@EXPERIMENTAL`` to the internal function ``be``.
>>    The macro is used when a symbol matures to become part of the stable ABI, to
>> -  provide an alias to experimental for some time.
>> +  provide an alias to experimental until the next major ABI version.
> 
> Why limiting the period for experimental status?
> Some API want to remain experimental longer.
> 
> [...]
>>  In situations in which an ``experimental`` symbol has been stable for some time,
>>  and it becomes a candidate for promotion to the stable ABI. At this time, when
>> -promoting the symbol, maintainer may choose to provide an alias to the
>> -``experimental`` symbol version, so as not to break consuming applications.
>> +promoting the symbol, the maintainer may choose to provide an alias to the
>> +``experimental`` symbol version, so as not to break consuming applications. This
> 
> Please start a sentence on a new line.

ACK

> 
>> +alias will then typically be dropped in the next major ABI version.
> 
> I don't see the need for the time estimation.
> 
> 

Will reword to ...

"This alias will then be dropped in the next major ABI version."

Re: [dpdk-dev] [PATCH v1 2/2] doc: clarify alias to experimental period

[Thomas Monjalon]

07/07/2020 18:35, Kinsella, Ray:
> On 07/07/2020 16:26, Thomas Monjalon wrote:
> > 07/07/2020 16:45, Ray Kinsella:
> >> Clarify retention period for aliases to experimental.
> >>
> >> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
> >> ---
> >> --- a/doc/guides/contributing/abi_versioning.rst
> >> +++ b/doc/guides/contributing/abi_versioning.rst
> >> @@ -158,7 +158,7 @@ The macros exported are:
> >>  * ``VERSION_SYMBOL_EXPERIMENTAL(b, e)``: Creates a symbol version table entry
> >>    binding versioned symbol ``b@EXPERIMENTAL`` to the internal function ``be``.
> >>    The macro is used when a symbol matures to become part of the stable ABI, to
> >> -  provide an alias to experimental for some time.
> >> +  provide an alias to experimental until the next major ABI version.
> > 
> > Why limiting the period for experimental status?
> > Some API want to remain experimental longer.
> > 
> > [...]
> >>  In situations in which an ``experimental`` symbol has been stable for some time,
> >>  and it becomes a candidate for promotion to the stable ABI. At this time, when
> >> -promoting the symbol, maintainer may choose to provide an alias to the
> >> -``experimental`` symbol version, so as not to break consuming applications.
> >> +promoting the symbol, the maintainer may choose to provide an alias to the
> >> +``experimental`` symbol version, so as not to break consuming applications. This
> > 
> > Please start a sentence on a new line.
> 
> ACK
> 
> > 
> >> +alias will then typically be dropped in the next major ABI version.
> > 
> > I don't see the need for the time estimation.
> > 
> > 
> 
> Will reword to ...
> 
> "This alias will then be dropped in the next major ABI version."

It is not addressing my first comment. Please see above.

Re: [dpdk-dev] [PATCH v1 2/2] doc: clarify alias to experimental period

[Kinsella, Ray]

On 07/07/2020 17:36, Thomas Monjalon wrote:
> 07/07/2020 18:35, Kinsella, Ray:
>> On 07/07/2020 16:26, Thomas Monjalon wrote:
>>> 07/07/2020 16:45, Ray Kinsella:
>>>> Clarify retention period for aliases to experimental.
>>>>
>>>> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
>>>> ---
>>>> --- a/doc/guides/contributing/abi_versioning.rst
>>>> +++ b/doc/guides/contributing/abi_versioning.rst
>>>> @@ -158,7 +158,7 @@ The macros exported are:
>>>>  * ``VERSION_SYMBOL_EXPERIMENTAL(b, e)``: Creates a symbol version table entry
>>>>    binding versioned symbol ``b@EXPERIMENTAL`` to the internal function ``be``.
>>>>    The macro is used when a symbol matures to become part of the stable ABI, to
>>>> -  provide an alias to experimental for some time.
>>>> +  provide an alias to experimental until the next major ABI version.
>>>
>>> Why limiting the period for experimental status?
>>> Some API want to remain experimental longer.
>>>
>>> [...]
>>>>  In situations in which an ``experimental`` symbol has been stable for some time,
>>>>  and it becomes a candidate for promotion to the stable ABI. At this time, when
>>>> -promoting the symbol, maintainer may choose to provide an alias to the
>>>> -``experimental`` symbol version, so as not to break consuming applications.
>>>> +promoting the symbol, the maintainer may choose to provide an alias to the
>>>> +``experimental`` symbol version, so as not to break consuming applications. This
>>>
>>> Please start a sentence on a new line.
>>
>> ACK
>>
>>>
>>>> +alias will then typically be dropped in the next major ABI version.
>>>
>>> I don't see the need for the time estimation.
>>>
>>>
>>
>> Will reword to ...
>>
>> "This alias will then be dropped in the next major ABI version."
> 
> It is not addressing my first comment. Please see above.
> 

Thank you, I don't necessarily agree with the first comment :-)
We need to say when the alias should be dropped no?

Re: [dpdk-dev] [PATCH v1 2/2] doc: clarify alias to experimental period

[Honnappa Nagarahalli]

<snip>

> Subject: Re: [PATCH v1 2/2] doc: clarify alias to experimental period
> 
> 
> 
> On 07/07/2020 17:36, Thomas Monjalon wrote:
> > 07/07/2020 18:35, Kinsella, Ray:
> >> On 07/07/2020 16:26, Thomas Monjalon wrote:
> >>> 07/07/2020 16:45, Ray Kinsella:
> >>>> Clarify retention period for aliases to experimental.
> >>>>
> >>>> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
> >>>> ---
> >>>> --- a/doc/guides/contributing/abi_versioning.rst
> >>>> +++ b/doc/guides/contributing/abi_versioning.rst
> >>>> @@ -158,7 +158,7 @@ The macros exported are:
> >>>>  * ``VERSION_SYMBOL_EXPERIMENTAL(b, e)``: Creates a symbol version
> table entry
> >>>>    binding versioned symbol ``b@EXPERIMENTAL`` to the internal
> function ``be``.
> >>>>    The macro is used when a symbol matures to become part of the
> >>>> stable ABI, to
> >>>> -  provide an alias to experimental for some time.
> >>>> +  provide an alias to experimental until the next major ABI version.
> >>>
> >>> Why limiting the period for experimental status?
> >>> Some API want to remain experimental longer.
This is not limiting the period. This is about how long VERSION_SYMBOL_EXPERIMENTAL should be in place for a symbol after the experimental tag is removed for the symbol.

> >>>
> >>> [...]
> >>>>  In situations in which an ``experimental`` symbol has been stable
> >>>> for some time,  and it becomes a candidate for promotion to the
> >>>> stable ABI. At this time, when -promoting the symbol, maintainer
> >>>> may choose to provide an alias to the -``experimental`` symbol version,
> so as not to break consuming applications.
> >>>> +promoting the symbol, the maintainer may choose to provide an
> >>>> +alias to the ``experimental`` symbol version, so as not to break
> >>>> +consuming applications. This
> >>>
> >>> Please start a sentence on a new line.
> >>
> >> ACK
> >>
> >>>
> >>>> +alias will then typically be dropped in the next major ABI version.
> >>>
> >>> I don't see the need for the time estimation.
I prefer this wording as it clarifying what should be done while creating a patch.

> >>>
> >>>
> >>
> >> Will reword to ...
> >>
> >> "This alias will then be dropped in the next major ABI version."
> >
> > It is not addressing my first comment. Please see above.
> >
> 
> Thank you, I don't necessarily agree with the first comment :-) We need to say
> when the alias should be dropped no?

Re: [dpdk-dev] [PATCH v1 2/2] doc: clarify alias to experimental period

[Thomas Monjalon]

07/07/2020 18:37, Kinsella, Ray:
> 
> On 07/07/2020 17:36, Thomas Monjalon wrote:
> > 07/07/2020 18:35, Kinsella, Ray:
> >> On 07/07/2020 16:26, Thomas Monjalon wrote:
> >>> 07/07/2020 16:45, Ray Kinsella:
> >>>> Clarify retention period for aliases to experimental.
> >>>>
> >>>> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
> >>>> ---
> >>>> --- a/doc/guides/contributing/abi_versioning.rst
> >>>> +++ b/doc/guides/contributing/abi_versioning.rst
> >>>> @@ -158,7 +158,7 @@ The macros exported are:
> >>>>  * ``VERSION_SYMBOL_EXPERIMENTAL(b, e)``: Creates a symbol version table entry
> >>>>    binding versioned symbol ``b@EXPERIMENTAL`` to the internal function ``be``.
> >>>>    The macro is used when a symbol matures to become part of the stable ABI, to
> >>>> -  provide an alias to experimental for some time.
> >>>> +  provide an alias to experimental until the next major ABI version.
> >>>
> >>> Why limiting the period for experimental status?
> >>> Some API want to remain experimental longer.
> >>>
> >>> [...]
> >>>> +alias will then typically be dropped in the next major ABI version.
> >>>
> >>> I don't see the need for the time estimation.
> >>
> >> Will reword to ...
> >>
> >> "This alias will then be dropped in the next major ABI version."
> > 
> > It is not addressing my first comment. Please see above.
> 
> Thank you, I don't necessarily agree with the first comment :-)

You don't have to agree. But in this case we must discuss :-)

> We need to say when the alias should be dropped no?

I don't think so.
Until now, it is let to the appreciation of the maintainer.
If we want to change the rule, especially for experimental period,
it must be said clearly and debated.

Re: [dpdk-dev] [PATCH v1 2/2] doc: clarify alias to experimental period

[Thomas Monjalon]

07/07/2020 18:55, Honnappa Nagarahalli:
> > On 07/07/2020 17:36, Thomas Monjalon wrote:
> > > 07/07/2020 18:35, Kinsella, Ray:
> > >> On 07/07/2020 16:26, Thomas Monjalon wrote:
> > >>> 07/07/2020 16:45, Ray Kinsella:
> > >>>> Clarify retention period for aliases to experimental.
> > >>>>
> > >>>> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
> > >>>> ---
> > >>>> --- a/doc/guides/contributing/abi_versioning.rst
> > >>>> +++ b/doc/guides/contributing/abi_versioning.rst
> > >>>> @@ -158,7 +158,7 @@ The macros exported are:
> > >>>>  * ``VERSION_SYMBOL_EXPERIMENTAL(b, e)``: Creates a symbol version
> > table entry
> > >>>>    binding versioned symbol ``b@EXPERIMENTAL`` to the internal
> > function ``be``.
> > >>>>    The macro is used when a symbol matures to become part of the
> > >>>> stable ABI, to
> > >>>> -  provide an alias to experimental for some time.
> > >>>> +  provide an alias to experimental until the next major ABI version.
> > >>>
> > >>> Why limiting the period for experimental status?
> > >>> Some API want to remain experimental longer.
> 
> This is not limiting the period.
> This is about how long VERSION_SYMBOL_EXPERIMENTAL should be in place
> for a symbol after the experimental tag is removed for the symbol.

Oh wait, I was wrong. It is only about the alias which is set
AFTER the experimental period.

> > >>> [...]
> > >>>>  In situations in which an ``experimental`` symbol has been stable
> > >>>> for some time,  and it becomes a candidate for promotion to the
> > >>>> stable ABI. At this time, when -promoting the symbol, maintainer
> > >>>> may choose to provide an alias to the -``experimental`` symbol version,
> > so as not to break consuming applications.
> > >>>> +promoting the symbol, the maintainer may choose to provide an
> > >>>> +alias to the ``experimental`` symbol version, so as not to break
> > >>>> +consuming applications. This
> > >>>
> > >>> Please start a sentence on a new line.
> > >>
> > >> ACK
> > >>
> > >>>
> > >>>> +alias will then typically be dropped in the next major ABI version.
> > >>>
> > >>> I don't see the need for the time estimation.
> 
> I prefer this wording as it clarifying what should be done while creating a patch.

Yes, after a second read, I am OK.

Re: [dpdk-dev] [PATCH v1 2/2] doc: clarify alias to experimental period

[Kinsella, Ray]

On 07/07/2020 17:57, Thomas Monjalon wrote:
> 07/07/2020 18:37, Kinsella, Ray:
>>
>> On 07/07/2020 17:36, Thomas Monjalon wrote:
>>> 07/07/2020 18:35, Kinsella, Ray:
>>>> On 07/07/2020 16:26, Thomas Monjalon wrote:
>>>>> 07/07/2020 16:45, Ray Kinsella:
>>>>>> Clarify retention period for aliases to experimental.
>>>>>>
>>>>>> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
>>>>>> ---
>>>>>> --- a/doc/guides/contributing/abi_versioning.rst
>>>>>> +++ b/doc/guides/contributing/abi_versioning.rst
>>>>>> @@ -158,7 +158,7 @@ The macros exported are:
>>>>>>  * ``VERSION_SYMBOL_EXPERIMENTAL(b, e)``: Creates a symbol version table entry
>>>>>>    binding versioned symbol ``b@EXPERIMENTAL`` to the internal function ``be``.
>>>>>>    The macro is used when a symbol matures to become part of the stable ABI, to
>>>>>> -  provide an alias to experimental for some time.
>>>>>> +  provide an alias to experimental until the next major ABI version.
>>>>>
>>>>> Why limiting the period for experimental status?
>>>>> Some API want to remain experimental longer.
>>>>>
>>>>> [...]
>>>>>> +alias will then typically be dropped in the next major ABI version.
>>>>>
>>>>> I don't see the need for the time estimation.
>>>>
>>>> Will reword to ...
>>>>
>>>> "This alias will then be dropped in the next major ABI version."
>>>
>>> It is not addressing my first comment. Please see above.
>>
>> Thank you, I don't necessarily agree with the first comment :-)
> 
> You don't have to agree. But in this case we must discuss :-)
> 
>> We need to say when the alias should be dropped no?
> 
> I don't think so.
> Until now, it is let to the appreciation of the maintainer.
> If we want to change the rule, especially for experimental period,
> it must be said clearly and debated.

It doesn't make _any_ sense to maintain an alias after the new ABI.

The alias is there to maintain ABI compatibility, 
there is no reason to maintain compatibility in the new ABI - so it should be dropped

 

Re: [dpdk-dev] [PATCH v1 2/2] doc: clarify alias to experimental period

[Kinsella, Ray]

On 07/07/2020 18:00, Thomas Monjalon wrote:
> 07/07/2020 18:55, Honnappa Nagarahalli:
>>> On 07/07/2020 17:36, Thomas Monjalon wrote:
>>>> 07/07/2020 18:35, Kinsella, Ray:
>>>>> On 07/07/2020 16:26, Thomas Monjalon wrote:
>>>>>> 07/07/2020 16:45, Ray Kinsella:
>>>>>>> Clarify retention period for aliases to experimental.
>>>>>>>
>>>>>>> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
>>>>>>> ---
>>>>>>> --- a/doc/guides/contributing/abi_versioning.rst
>>>>>>> +++ b/doc/guides/contributing/abi_versioning.rst
>>>>>>> @@ -158,7 +158,7 @@ The macros exported are:
>>>>>>>  * ``VERSION_SYMBOL_EXPERIMENTAL(b, e)``: Creates a symbol version
>>> table entry
>>>>>>>    binding versioned symbol ``b@EXPERIMENTAL`` to the internal
>>> function ``be``.
>>>>>>>    The macro is used when a symbol matures to become part of the
>>>>>>> stable ABI, to
>>>>>>> -  provide an alias to experimental for some time.
>>>>>>> +  provide an alias to experimental until the next major ABI version.
>>>>>>
>>>>>> Why limiting the period for experimental status?
>>>>>> Some API want to remain experimental longer.
>>
>> This is not limiting the period.
>> This is about how long VERSION_SYMBOL_EXPERIMENTAL should be in place
>> for a symbol after the experimental tag is removed for the symbol.
> 
> Oh wait, I was wrong. It is only about the alias which is set
> AFTER the experimental period.
> 
>>>>>> [...]
>>>>>>>  In situations in which an ``experimental`` symbol has been stable
>>>>>>> for some time,  and it becomes a candidate for promotion to the
>>>>>>> stable ABI. At this time, when -promoting the symbol, maintainer
>>>>>>> may choose to provide an alias to the -``experimental`` symbol version,
>>> so as not to break consuming applications.
>>>>>>> +promoting the symbol, the maintainer may choose to provide an
>>>>>>> +alias to the ``experimental`` symbol version, so as not to break
>>>>>>> +consuming applications. This
>>>>>>
>>>>>> Please start a sentence on a new line.
>>>>>
>>>>> ACK
>>>>>
>>>>>>
>>>>>>> +alias will then typically be dropped in the next major ABI version.
>>>>>>
>>>>>> I don't see the need for the time estimation.
>>
>> I prefer this wording as it clarifying what should be done while creating a patch.
> 
> Yes, after a second read, I am OK.
> 
perfect, I will sort out the other bits. 

Re: [dpdk-dev] [PATCH v1 2/2] doc: clarify alias to experimental period

[Thomas Monjalon]

07/07/2020 19:01, Kinsella, Ray:
> On 07/07/2020 17:57, Thomas Monjalon wrote:
> > 07/07/2020 18:37, Kinsella, Ray:
> >> On 07/07/2020 17:36, Thomas Monjalon wrote:
> >>> 07/07/2020 18:35, Kinsella, Ray:
> >>>> On 07/07/2020 16:26, Thomas Monjalon wrote:
> >>>>> 07/07/2020 16:45, Ray Kinsella:
> >>>>>> Clarify retention period for aliases to experimental.
> >>>>>>
> >>>>>> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
> >>>>>> ---
> >>>>>> --- a/doc/guides/contributing/abi_versioning.rst
> >>>>>> +++ b/doc/guides/contributing/abi_versioning.rst
> >>>>>> @@ -158,7 +158,7 @@ The macros exported are:
> >>>>>>  * ``VERSION_SYMBOL_EXPERIMENTAL(b, e)``: Creates a symbol version table entry
> >>>>>>    binding versioned symbol ``b@EXPERIMENTAL`` to the internal function ``be``.
> >>>>>>    The macro is used when a symbol matures to become part of the stable ABI, to
> >>>>>> -  provide an alias to experimental for some time.
> >>>>>> +  provide an alias to experimental until the next major ABI version.
> >>>>>
> >>>>> Why limiting the period for experimental status?
> >>>>> Some API want to remain experimental longer.
> >>>>>
> >>>>> [...]
> >>>>>> +alias will then typically be dropped in the next major ABI version.
> >>>>>
> >>>>> I don't see the need for the time estimation.
> >>>>
> >>>> Will reword to ...
> >>>>
> >>>> "This alias will then be dropped in the next major ABI version."
> >>>
> >>> It is not addressing my first comment. Please see above.
> >>
> >> Thank you, I don't necessarily agree with the first comment :-)
> > 
> > You don't have to agree. But in this case we must discuss :-)
> > 
> >> We need to say when the alias should be dropped no?
> > 
> > I don't think so.
> > Until now, it is let to the appreciation of the maintainer.
> > If we want to change the rule, especially for experimental period,
> > it must be said clearly and debated.
> 
> It doesn't make _any_ sense to maintain an alias after the new ABI.
> 
> The alias is there to maintain ABI compatibility, 
> there is no reason to maintain compatibility in the new ABI - so it should be dropped

Yes I was wrong, sorry.

[dpdk-dev] [PATCH v2 0/2] doc: minor abi policy fixes

[Ray Kinsella]

Few documentation fixexs, clarifing the Windows ABI policy and aliases to
experimental mode.

Ray Kinsella (2):
  doc: reword abi policy for windows
  doc: clarify alias to experimental period

v2:
  Addressed feedback from Thomas Monjalon.

 doc/guides/contributing/abi_policy.rst     | 4 +++-
 doc/guides/contributing/abi_versioning.rst | 5 +++--
 doc/guides/windows_gsg/intro.rst           | 6 +++---
 3 files changed, 9 insertions(+), 6 deletions(-)

--
2.7.4

[dpdk-dev] [PATCH v2 1/2] doc: reword abi policy for windows

[Ray Kinsella]

Minor changes to the abi policy for windows.

Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
---
 doc/guides/contributing/abi_policy.rst | 4 +++-
 doc/guides/windows_gsg/intro.rst       | 6 +++---
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
index d0affa9..4452362 100644
--- a/doc/guides/contributing/abi_policy.rst
+++ b/doc/guides/contributing/abi_policy.rst
@@ -40,7 +40,9 @@ General Guidelines
    maintaining ABI stability through one year of DPDK releases starting from
    DPDK 19.11. This policy will be reviewed in 2020, with intention of
    lengthening the stability period. Additional implementation detail can be
-   found in the :ref:`release notes <20_02_abi_changes>`.
+   found in the :ref:`release notes <20_02_abi_changes>`. Please note that this
+   policy does not currently apply to the :doc:`Windows build
+   <../windows_gsg/intro>`.
 
 What is an ABI?
 ~~~~~~~~~~~~~~~
diff --git a/doc/guides/windows_gsg/intro.rst b/doc/guides/windows_gsg/intro.rst
index 58c6246..4ac7f97 100644
--- a/doc/guides/windows_gsg/intro.rst
+++ b/doc/guides/windows_gsg/intro.rst
@@ -19,6 +19,6 @@ compile. Support is being added in pieces so as to limit the overall scope
 of any individual patch series. The goal is to be able to run any DPDK
 application natively on Windows.
 
-The :doc:`../contributing/abi_policy` cannot be respected for Windows.
-Minor ABI versions may be incompatible
-because function versioning is not supported on Windows.
+The :doc:`../contributing/abi_policy` does not apply to the Windows build,
+as function versioning is not supported on Windows,
+therefore minor ABI versions may be incompatible.
-- 
2.7.4

[dpdk-dev] [PATCH v2 2/2] doc: clarify alias to experimental period

[Ray Kinsella]

Clarify retention period for aliases to experimental.

Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
---
 doc/guides/contributing/abi_versioning.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/doc/guides/contributing/abi_versioning.rst b/doc/guides/contributing/abi_versioning.rst
index 31a9205..b1d09c7 100644
--- a/doc/guides/contributing/abi_versioning.rst
+++ b/doc/guides/contributing/abi_versioning.rst
@@ -158,7 +158,7 @@ The macros exported are:
 * ``VERSION_SYMBOL_EXPERIMENTAL(b, e)``: Creates a symbol version table entry
   binding versioned symbol ``b@EXPERIMENTAL`` to the internal function ``be``.
   The macro is used when a symbol matures to become part of the stable ABI, to
-  provide an alias to experimental for some time.
+  provide an alias to experimental until the next major ABI version.
 
 .. _example_abi_macro_usage:
 
@@ -428,8 +428,9 @@ _____________________________
 
 In situations in which an ``experimental`` symbol has been stable for some time,
 and it becomes a candidate for promotion to the stable ABI. At this time, when
-promoting the symbol, maintainer may choose to provide an alias to the
+promoting the symbol, the maintainer may choose to provide an alias to the
 ``experimental`` symbol version, so as not to break consuming applications.
+This alias is then dropped in the next major ABI version.
 
 The process to provide an alias to ``experimental`` is similar to that, of
 :ref:`symbol versioning <example_abi_macro_usage>` described above.
-- 
2.7.4

Re: [dpdk-dev] [PATCH v2 2/2] doc: clarify alias to experimental period

[Honnappa Nagarahalli]

<snip>

> Subject: [PATCH v2 2/2] doc: clarify alias to experimental period
> 
> Clarify retention period for aliases to experimental.
> 
> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
Reviewed-by: Honnappa Nagarahalli <honnappa.nagarahalli@arm.com>

> ---
>  doc/guides/contributing/abi_versioning.rst | 5 +++--
>  1 file changed, 3 insertions(+), 2 deletions(-)
> 
> diff --git a/doc/guides/contributing/abi_versioning.rst
> b/doc/guides/contributing/abi_versioning.rst
> index 31a9205..b1d09c7 100644
> --- a/doc/guides/contributing/abi_versioning.rst
> +++ b/doc/guides/contributing/abi_versioning.rst
> @@ -158,7 +158,7 @@ The macros exported are:
>  * ``VERSION_SYMBOL_EXPERIMENTAL(b, e)``: Creates a symbol version table
> entry
>    binding versioned symbol ``b@EXPERIMENTAL`` to the internal function
> ``be``.
>    The macro is used when a symbol matures to become part of the stable ABI,
> to
> -  provide an alias to experimental for some time.
> +  provide an alias to experimental until the next major ABI version.
> 
>  .. _example_abi_macro_usage:
> 
> @@ -428,8 +428,9 @@ _____________________________
> 
>  In situations in which an ``experimental`` symbol has been stable for some
> time,  and it becomes a candidate for promotion to the stable ABI. At this
> time, when -promoting the symbol, maintainer may choose to provide an
> alias to the
> +promoting the symbol, the maintainer may choose to provide an alias to
> +the
>  ``experimental`` symbol version, so as not to break consuming applications.
> +This alias is then dropped in the next major ABI version.
> 
>  The process to provide an alias to ``experimental`` is similar to that,
> of  :ref:`symbol versioning <example_abi_macro_usage>` described above.
> --
> 2.7.4

Re: [dpdk-dev] [PATCH v2 0/2] doc: minor abi policy fixes

[Thomas Monjalon]

07/07/2020 19:50, Ray Kinsella:
> Few documentation fixexs, clarifing the Windows ABI policy and aliases to
> experimental mode.
> 
> Ray Kinsella (2):
>   doc: reword abi policy for windows
>   doc: clarify alias to experimental period
> 
> v2:
>   Addressed feedback from Thomas Monjalon.

One more sentence needs to start on its line,
avoiding to split a link on two lines.

Reworded titles with uppercases as well:
	doc: reword ABI policy for Windows
	doc: clarify period of alias to experimental symbol

Applied with above changes, thanks

Re: [dpdk-dev] [PATCH v2 0/2] doc: minor abi policy fixes

[Kinsella, Ray]

On 08/07/2020 11:32, Thomas Monjalon wrote:
> 07/07/2020 19:50, Ray Kinsella:
>> Few documentation fixexs, clarifing the Windows ABI policy and aliases to
>> experimental mode.
>>
>> Ray Kinsella (2):
>>   doc: reword abi policy for windows
>>   doc: clarify alias to experimental period
>>
>> v2:
>>   Addressed feedback from Thomas Monjalon.
> 
> One more sentence needs to start on its line,
> avoiding to split a link on two lines.

ah yes, missed that one sorry.
> 
> Reworded titles with uppercases as well:
> 	doc: reword ABI policy for Windows
> 	doc: clarify period of alias to experimental symbol
> 
> Applied with above changes, thanks
> 
>