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 <m...@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.
