<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 <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.
> >>> > >>> [...] > >>>> 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?
