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
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
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
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.
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.
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 :-)
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."
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.
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?
<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?
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.
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.
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
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.
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.
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
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
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
<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
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
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 > >