DPDK patches and discussions
 help / color / mirror / Atom feed
* [dpdk-dev] [PATCH v1 0/2] doc: minor abi policy fixes
@ 2020-07-07 14:45 Ray Kinsella
  2020-07-07 14:45 ` [dpdk-dev] [PATCH v1 1/2] doc: reword abi policy for windows Ray Kinsella
                   ` (2 more replies)
  0 siblings, 3 replies; 21+ messages in thread
From: Ray Kinsella @ 2020-07-07 14:45 UTC (permalink / raw)
  To: dev
  Cc: fady, thomas, Honnappa.Nagarahalli, Ray Kinsella, Neil Horman,
	John McNamara, Marko Kovacevic, Harini Ramakrishnan,
	Omar Cardona, Pallavi Kadam, Ranjit Menon

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

^ permalink raw reply	[flat|nested] 21+ messages in thread

* [dpdk-dev] [PATCH v1 1/2] doc: reword abi policy for windows
  2020-07-07 14:45 [dpdk-dev] [PATCH v1 0/2] doc: minor abi policy fixes Ray Kinsella
@ 2020-07-07 14:45 ` Ray Kinsella
  2020-07-07 15:23   ` Thomas Monjalon
  2020-07-07 14:45 ` [dpdk-dev] [PATCH v1 2/2] doc: clarify alias to experimental period Ray Kinsella
  2020-07-07 17:50 ` [dpdk-dev] [PATCH v2 0/2] doc: minor abi policy fixes Ray Kinsella
  2 siblings, 1 reply; 21+ messages in thread
From: Ray Kinsella @ 2020-07-07 14:45 UTC (permalink / raw)
  To: dev
  Cc: fady, thomas, Honnappa.Nagarahalli, Ray Kinsella, Neil Horman,
	John McNamara, Marko Kovacevic, Harini Ramakrishnan,
	Omar Cardona, Pallavi Kadam, Ranjit Menon

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


^ permalink raw reply	[flat|nested] 21+ messages in thread

* [dpdk-dev] [PATCH v1 2/2] doc: clarify alias to experimental period
  2020-07-07 14:45 [dpdk-dev] [PATCH v1 0/2] doc: minor abi policy fixes Ray Kinsella
  2020-07-07 14:45 ` [dpdk-dev] [PATCH v1 1/2] doc: reword abi policy for windows Ray Kinsella
@ 2020-07-07 14:45 ` Ray Kinsella
  2020-07-07 15:26   ` Thomas Monjalon
  2020-07-07 17:50 ` [dpdk-dev] [PATCH v2 0/2] doc: minor abi policy fixes Ray Kinsella
  2 siblings, 1 reply; 21+ messages in thread
From: Ray Kinsella @ 2020-07-07 14:45 UTC (permalink / raw)
  To: dev
  Cc: fady, thomas, Honnappa.Nagarahalli, Ray Kinsella, Neil Horman,
	John McNamara, Marko Kovacevic, Harini Ramakrishnan,
	Omar Cardona, Pallavi Kadam, Ranjit Menon

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


^ permalink raw reply	[flat|nested] 21+ messages in thread

* Re: [dpdk-dev] [PATCH v1 1/2] doc: reword abi policy for windows
  2020-07-07 14:45 ` [dpdk-dev] [PATCH v1 1/2] doc: reword abi policy for windows Ray Kinsella
@ 2020-07-07 15:23   ` Thomas Monjalon
  2020-07-07 16:33     ` Kinsella, Ray
  0 siblings, 1 reply; 21+ messages in thread
From: Thomas Monjalon @ 2020-07-07 15:23 UTC (permalink / raw)
  To: Ray Kinsella
  Cc: dev, fady, Honnappa.Nagarahalli, Ray Kinsella, Neil Horman,
	John McNamara, Marko Kovacevic, Harini Ramakrishnan,
	Omar Cardona, Pallavi Kadam, Ranjit Menon, talshn

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.




^ permalink raw reply	[flat|nested] 21+ messages in thread

* Re: [dpdk-dev] [PATCH v1 2/2] doc: clarify alias to experimental period
  2020-07-07 14:45 ` [dpdk-dev] [PATCH v1 2/2] doc: clarify alias to experimental period Ray Kinsella
@ 2020-07-07 15:26   ` Thomas Monjalon
  2020-07-07 16:35     ` Kinsella, Ray
  0 siblings, 1 reply; 21+ messages in thread
From: Thomas Monjalon @ 2020-07-07 15:26 UTC (permalink / raw)
  To: Ray Kinsella
  Cc: dev, fady, Honnappa.Nagarahalli, Ray Kinsella, Neil Horman,
	John McNamara, Marko Kovacevic, Harini Ramakrishnan,
	Omar Cardona, Pallavi Kadam, Ranjit Menon, david.marchand,
	nhorman, bruce.richardson

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.



^ permalink raw reply	[flat|nested] 21+ messages in thread

* Re: [dpdk-dev] [PATCH v1 1/2] doc: reword abi policy for windows
  2020-07-07 15:23   ` Thomas Monjalon
@ 2020-07-07 16:33     ` Kinsella, Ray
  0 siblings, 0 replies; 21+ messages in thread
From: Kinsella, Ray @ 2020-07-07 16:33 UTC (permalink / raw)
  To: Thomas Monjalon
  Cc: dev, fady, Honnappa.Nagarahalli, Neil Horman, John McNamara,
	Marko Kovacevic, Harini Ramakrishnan, Omar Cardona,
	Pallavi Kadam, Ranjit Menon, talshn



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 :-)
 

^ permalink raw reply	[flat|nested] 21+ messages in thread

* Re: [dpdk-dev] [PATCH v1 2/2] doc: clarify alias to experimental period
  2020-07-07 15:26   ` Thomas Monjalon
@ 2020-07-07 16:35     ` Kinsella, Ray
  2020-07-07 16:36       ` Thomas Monjalon
  0 siblings, 1 reply; 21+ messages in thread
From: Kinsella, Ray @ 2020-07-07 16:35 UTC (permalink / raw)
  To: Thomas Monjalon
  Cc: dev, fady, Honnappa.Nagarahalli, Neil Horman, John McNamara,
	Marko Kovacevic, Harini Ramakrishnan, Omar Cardona,
	Pallavi Kadam, Ranjit Menon, david.marchand, bruce.richardson



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."

^ permalink raw reply	[flat|nested] 21+ messages in thread

* Re: [dpdk-dev] [PATCH v1 2/2] doc: clarify alias to experimental period
  2020-07-07 16:35     ` Kinsella, Ray
@ 2020-07-07 16:36       ` Thomas Monjalon
  2020-07-07 16:37         ` Kinsella, Ray
  0 siblings, 1 reply; 21+ messages in thread
From: Thomas Monjalon @ 2020-07-07 16:36 UTC (permalink / raw)
  To: Kinsella, Ray
  Cc: dev, fady, Honnappa.Nagarahalli, Neil Horman, John McNamara,
	Marko Kovacevic, Harini Ramakrishnan, Omar Cardona,
	Pallavi Kadam, Ranjit Menon, david.marchand, bruce.richardson

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.




^ permalink raw reply	[flat|nested] 21+ messages in thread

* Re: [dpdk-dev] [PATCH v1 2/2] doc: clarify alias to experimental period
  2020-07-07 16:36       ` Thomas Monjalon
@ 2020-07-07 16:37         ` Kinsella, Ray
  2020-07-07 16:55           ` Honnappa Nagarahalli
  2020-07-07 16:57           ` Thomas Monjalon
  0 siblings, 2 replies; 21+ messages in thread
From: Kinsella, Ray @ 2020-07-07 16:37 UTC (permalink / raw)
  To: Thomas Monjalon
  Cc: dev, fady, Honnappa.Nagarahalli, Neil Horman, John McNamara,
	Marko Kovacevic, Harini Ramakrishnan, Omar Cardona,
	Pallavi Kadam, Ranjit Menon, david.marchand, bruce.richardson



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?

^ permalink raw reply	[flat|nested] 21+ messages in thread

* Re: [dpdk-dev] [PATCH v1 2/2] doc: clarify alias to experimental period
  2020-07-07 16:37         ` Kinsella, Ray
@ 2020-07-07 16:55           ` Honnappa Nagarahalli
  2020-07-07 17:00             ` Thomas Monjalon
  2020-07-07 16:57           ` Thomas Monjalon
  1 sibling, 1 reply; 21+ messages in thread
From: Honnappa Nagarahalli @ 2020-07-07 16:55 UTC (permalink / raw)
  To: Kinsella, Ray, thomas
  Cc: dev, fady, Neil Horman, John McNamara, Marko Kovacevic,
	Harini Ramakrishnan, Omar Cardona, Pallavi Kadam, Ranjit Menon,
	david.marchand, bruce.richardson, Honnappa Nagarahalli, nd, nd

<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?

^ permalink raw reply	[flat|nested] 21+ messages in thread

* Re: [dpdk-dev] [PATCH v1 2/2] doc: clarify alias to experimental period
  2020-07-07 16:37         ` Kinsella, Ray
  2020-07-07 16:55           ` Honnappa Nagarahalli
@ 2020-07-07 16:57           ` Thomas Monjalon
  2020-07-07 17:01             ` Kinsella, Ray
  1 sibling, 1 reply; 21+ messages in thread
From: Thomas Monjalon @ 2020-07-07 16:57 UTC (permalink / raw)
  To: Kinsella, Ray
  Cc: dev, fady, Honnappa.Nagarahalli, Neil Horman, John McNamara,
	Marko Kovacevic, Harini Ramakrishnan, Omar Cardona,
	Pallavi Kadam, Ranjit Menon, david.marchand, bruce.richardson

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.



^ permalink raw reply	[flat|nested] 21+ messages in thread

* Re: [dpdk-dev] [PATCH v1 2/2] doc: clarify alias to experimental period
  2020-07-07 16:55           ` Honnappa Nagarahalli
@ 2020-07-07 17:00             ` Thomas Monjalon
  2020-07-07 17:01               ` Kinsella, Ray
  0 siblings, 1 reply; 21+ messages in thread
From: Thomas Monjalon @ 2020-07-07 17:00 UTC (permalink / raw)
  To: Kinsella, Ray, Honnappa Nagarahalli
  Cc: dev, fady, Neil Horman, John McNamara, Marko Kovacevic,
	Harini Ramakrishnan, Omar Cardona, Pallavi Kadam, Ranjit Menon,
	david.marchand, bruce.richardson, nd

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.




^ permalink raw reply	[flat|nested] 21+ messages in thread

* Re: [dpdk-dev] [PATCH v1 2/2] doc: clarify alias to experimental period
  2020-07-07 16:57           ` Thomas Monjalon
@ 2020-07-07 17:01             ` Kinsella, Ray
  2020-07-07 17:08               ` Thomas Monjalon
  0 siblings, 1 reply; 21+ messages in thread
From: Kinsella, Ray @ 2020-07-07 17:01 UTC (permalink / raw)
  To: Thomas Monjalon
  Cc: dev, fady, Honnappa.Nagarahalli, Neil Horman, John McNamara,
	Marko Kovacevic, Harini Ramakrishnan, Omar Cardona,
	Pallavi Kadam, Ranjit Menon, david.marchand, bruce.richardson



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

 

^ permalink raw reply	[flat|nested] 21+ messages in thread

* Re: [dpdk-dev] [PATCH v1 2/2] doc: clarify alias to experimental period
  2020-07-07 17:00             ` Thomas Monjalon
@ 2020-07-07 17:01               ` Kinsella, Ray
  0 siblings, 0 replies; 21+ messages in thread
From: Kinsella, Ray @ 2020-07-07 17:01 UTC (permalink / raw)
  To: Thomas Monjalon, Honnappa Nagarahalli
  Cc: dev, fady, Neil Horman, John McNamara, Marko Kovacevic,
	Harini Ramakrishnan, Omar Cardona, Pallavi Kadam, Ranjit Menon,
	david.marchand, bruce.richardson, nd



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. 

^ permalink raw reply	[flat|nested] 21+ messages in thread

* Re: [dpdk-dev] [PATCH v1 2/2] doc: clarify alias to experimental period
  2020-07-07 17:01             ` Kinsella, Ray
@ 2020-07-07 17:08               ` Thomas Monjalon
  0 siblings, 0 replies; 21+ messages in thread
From: Thomas Monjalon @ 2020-07-07 17:08 UTC (permalink / raw)
  To: Kinsella, Ray
  Cc: dev, fady, Honnappa.Nagarahalli, Neil Horman, John McNamara,
	Marko Kovacevic, Harini Ramakrishnan, Omar Cardona,
	Pallavi Kadam, Ranjit Menon, david.marchand, bruce.richardson

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.



^ permalink raw reply	[flat|nested] 21+ messages in thread

* [dpdk-dev] [PATCH v2 0/2] doc: minor abi policy fixes
  2020-07-07 14:45 [dpdk-dev] [PATCH v1 0/2] doc: minor abi policy fixes Ray Kinsella
  2020-07-07 14:45 ` [dpdk-dev] [PATCH v1 1/2] doc: reword abi policy for windows Ray Kinsella
  2020-07-07 14:45 ` [dpdk-dev] [PATCH v1 2/2] doc: clarify alias to experimental period Ray Kinsella
@ 2020-07-07 17:50 ` Ray Kinsella
  2020-07-07 17:51   ` [dpdk-dev] [PATCH v2 1/2] doc: reword abi policy for windows Ray Kinsella
                     ` (2 more replies)
  2 siblings, 3 replies; 21+ messages in thread
From: Ray Kinsella @ 2020-07-07 17:50 UTC (permalink / raw)
  To: dev
  Cc: fady, thomas, Honnappa.Nagarahalli, Ray Kinsella, Neil Horman,
	John McNamara, Marko Kovacevic, Harini Ramakrishnan,
	Omar Cardona, Pallavi Kadam, Ranjit Menon

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

^ permalink raw reply	[flat|nested] 21+ messages in thread

* [dpdk-dev] [PATCH v2 1/2] doc: reword abi policy for windows
  2020-07-07 17:50 ` [dpdk-dev] [PATCH v2 0/2] doc: minor abi policy fixes Ray Kinsella
@ 2020-07-07 17:51   ` Ray Kinsella
  2020-07-07 17:51   ` [dpdk-dev] [PATCH v2 2/2] doc: clarify alias to experimental period Ray Kinsella
  2020-07-08 10:32   ` [dpdk-dev] [PATCH v2 0/2] doc: minor abi policy fixes Thomas Monjalon
  2 siblings, 0 replies; 21+ messages in thread
From: Ray Kinsella @ 2020-07-07 17:51 UTC (permalink / raw)
  To: dev
  Cc: fady, thomas, Honnappa.Nagarahalli, Ray Kinsella, Neil Horman,
	John McNamara, Marko Kovacevic, Harini Ramakrishnan,
	Omar Cardona, Pallavi Kadam, Ranjit Menon

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


^ permalink raw reply	[flat|nested] 21+ messages in thread

* [dpdk-dev] [PATCH v2 2/2] doc: clarify alias to experimental period
  2020-07-07 17:50 ` [dpdk-dev] [PATCH v2 0/2] doc: minor abi policy fixes Ray Kinsella
  2020-07-07 17:51   ` [dpdk-dev] [PATCH v2 1/2] doc: reword abi policy for windows Ray Kinsella
@ 2020-07-07 17:51   ` Ray Kinsella
  2020-07-07 18:44     ` Honnappa Nagarahalli
  2020-07-08 10:32   ` [dpdk-dev] [PATCH v2 0/2] doc: minor abi policy fixes Thomas Monjalon
  2 siblings, 1 reply; 21+ messages in thread
From: Ray Kinsella @ 2020-07-07 17:51 UTC (permalink / raw)
  To: dev
  Cc: fady, thomas, Honnappa.Nagarahalli, Ray Kinsella, Neil Horman,
	John McNamara, Marko Kovacevic, Harini Ramakrishnan,
	Omar Cardona, Pallavi Kadam, Ranjit Menon

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


^ permalink raw reply	[flat|nested] 21+ messages in thread

* Re: [dpdk-dev] [PATCH v2 2/2] doc: clarify alias to experimental period
  2020-07-07 17:51   ` [dpdk-dev] [PATCH v2 2/2] doc: clarify alias to experimental period Ray Kinsella
@ 2020-07-07 18:44     ` Honnappa Nagarahalli
  0 siblings, 0 replies; 21+ messages in thread
From: Honnappa Nagarahalli @ 2020-07-07 18:44 UTC (permalink / raw)
  To: Ray Kinsella, dev
  Cc: fady, thomas, Neil Horman, John McNamara, Marko Kovacevic,
	Harini Ramakrishnan, Omar Cardona, Pallavi Kadam, Ranjit Menon,
	Honnappa Nagarahalli, nd, nd

<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


^ permalink raw reply	[flat|nested] 21+ messages in thread

* Re: [dpdk-dev] [PATCH v2 0/2] doc: minor abi policy fixes
  2020-07-07 17:50 ` [dpdk-dev] [PATCH v2 0/2] doc: minor abi policy fixes Ray Kinsella
  2020-07-07 17:51   ` [dpdk-dev] [PATCH v2 1/2] doc: reword abi policy for windows Ray Kinsella
  2020-07-07 17:51   ` [dpdk-dev] [PATCH v2 2/2] doc: clarify alias to experimental period Ray Kinsella
@ 2020-07-08 10:32   ` Thomas Monjalon
  2020-07-08 12:02     ` Kinsella, Ray
  2 siblings, 1 reply; 21+ messages in thread
From: Thomas Monjalon @ 2020-07-08 10:32 UTC (permalink / raw)
  To: Ray Kinsella
  Cc: dev, fady, Honnappa.Nagarahalli, Neil Horman, John McNamara,
	Marko Kovacevic, Harini Ramakrishnan, Omar Cardona,
	Pallavi Kadam, Ranjit Menon

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



^ permalink raw reply	[flat|nested] 21+ messages in thread

* Re: [dpdk-dev] [PATCH v2 0/2] doc: minor abi policy fixes
  2020-07-08 10:32   ` [dpdk-dev] [PATCH v2 0/2] doc: minor abi policy fixes Thomas Monjalon
@ 2020-07-08 12:02     ` Kinsella, Ray
  0 siblings, 0 replies; 21+ messages in thread
From: Kinsella, Ray @ 2020-07-08 12:02 UTC (permalink / raw)
  To: Thomas Monjalon
  Cc: dev, fady, Honnappa.Nagarahalli, Neil Horman, John McNamara,
	Marko Kovacevic, Harini Ramakrishnan, Omar Cardona,
	Pallavi Kadam, Ranjit Menon



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
> 
> 

^ permalink raw reply	[flat|nested] 21+ messages in thread

end of thread, other threads:[~2020-07-08 12:02 UTC | newest]

Thread overview: 21+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-07-07 14:45 [dpdk-dev] [PATCH v1 0/2] doc: minor abi policy fixes Ray Kinsella
2020-07-07 14:45 ` [dpdk-dev] [PATCH v1 1/2] doc: reword abi policy for windows Ray Kinsella
2020-07-07 15:23   ` Thomas Monjalon
2020-07-07 16:33     ` Kinsella, Ray
2020-07-07 14:45 ` [dpdk-dev] [PATCH v1 2/2] doc: clarify alias to experimental period Ray Kinsella
2020-07-07 15:26   ` Thomas Monjalon
2020-07-07 16:35     ` Kinsella, Ray
2020-07-07 16:36       ` Thomas Monjalon
2020-07-07 16:37         ` Kinsella, Ray
2020-07-07 16:55           ` Honnappa Nagarahalli
2020-07-07 17:00             ` Thomas Monjalon
2020-07-07 17:01               ` Kinsella, Ray
2020-07-07 16:57           ` Thomas Monjalon
2020-07-07 17:01             ` Kinsella, Ray
2020-07-07 17:08               ` Thomas Monjalon
2020-07-07 17:50 ` [dpdk-dev] [PATCH v2 0/2] doc: minor abi policy fixes Ray Kinsella
2020-07-07 17:51   ` [dpdk-dev] [PATCH v2 1/2] doc: reword abi policy for windows Ray Kinsella
2020-07-07 17:51   ` [dpdk-dev] [PATCH v2 2/2] doc: clarify alias to experimental period Ray Kinsella
2020-07-07 18:44     ` Honnappa Nagarahalli
2020-07-08 10:32   ` [dpdk-dev] [PATCH v2 0/2] doc: minor abi policy fixes Thomas Monjalon
2020-07-08 12:02     ` Kinsella, Ray

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).