diff mbox series

[v1,2/2] doc: clarify alias to experimental period

Message ID 1594133126-2518-3-git-send-email-mdr@ashroe.eu (mailing list archive)
State Superseded, archived
Delegated to: Thomas Monjalon
Headers
Series doc: minor abi policy fixes |

Checks

Context Check Description
ci/checkpatch success coding style OK
ci/travis-robot success Travis build: passed
ci/Intel-compilation fail apply issues

Commit Message

Ray Kinsella July 7, 2020, 2:45 p.m. UTC 
  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(-)

Comments

Thomas Monjalon July 7, 2020, 3:26 p.m. UTC | #1 
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.
Ray Kinsella July 7, 2020, 4:35 p.m. UTC | #2 
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."
Thomas Monjalon July 7, 2020, 4:36 p.m. UTC | #3 
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.
Ray Kinsella July 7, 2020, 4:37 p.m. UTC | #4 
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?
Honnappa Nagarahalli July 7, 2020, 4:55 p.m. UTC | #5 
<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?
Thomas Monjalon July 7, 2020, 4:57 p.m. UTC | #6 
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.
Thomas Monjalon July 7, 2020, 5 p.m. UTC | #7 
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.
Ray Kinsella July 7, 2020, 5:01 p.m. UTC | #8 
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
Ray Kinsella July 7, 2020, 5:01 p.m. UTC | #9 
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.
Thomas Monjalon July 7, 2020, 5:08 p.m. UTC | #10 
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.
diff mbox series

Patch

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.