[FFmpeg-devel] [RFC/PATCH] doc/developer: clarify the criterion for removing deprecated APIs

[Michael Niedermayer]

On Mon, Jan 29, 2024 at 10:31:02AM +0100, Vittorio Giovara wrote:
> On Sun, Jan 28, 2024 at 11:47 PM Michael Niedermayer <michael at niedermayer.cc>
> wrote:
> 
> > On Sun, Jan 28, 2024 at 01:28:36PM +0100, Anton Khirnov wrote:
> > > Previously, the implicit standard was to wait 2 years before deprecation
> > > and removal, but it has been widely agreed at developer meetings that
> > > time-based measures do not make sense and we should switch to a
> > > release-based one instead.
> > > ---
> > > Feel welcome to argue for other numbers than 2, or suggest alternative
> > > criteria, but please try to limit bikeshedding.
> > > ---
> > >  doc/developer.texi | 3 ++-
> > >  1 file changed, 2 insertions(+), 1 deletion(-)
> > >
> > > diff --git a/doc/developer.texi b/doc/developer.texi
> > > index dd96e3b36a..3f3218f66a 100644
> > > --- a/doc/developer.texi
> > > +++ b/doc/developer.texi
> > > @@ -552,7 +552,8 @@ the negative effects on our callers, who are
> > required to adapt their code,
> > >  backward-incompatible changes during a major bump should be limited to:
> > >  @itemize @bullet
> > >  @item
> > > -Removing previously deprecated APIs.
> > > +Removing APIs that were marked as deprecated in at least two previous
> > > +major releases.
> >
> > Removing APIs that were marked as deprecated in at least two previous
> > major releases for at least 1 year.
> >
> > (goal of this proposed difference is to ensure that if for whatever reason
> >  we make several major releases in quick succession it doesnt deprecate
> >  things faster)
> >
> 
> IMO that's a bit verbose and given language is not precise it could lead to
> confusion (at least 1 year from deprecation? from a release with a
> deprecation warning? a mix of the two?)

You can suggest clearer language.

The advanagte of including a time period is that its easier for people
to plan things, as they know how long they can depend on an API.

thx

[...]
-- 
Michael     GnuPG fingerprint: 9FF2128B147EF6730BADF133611EC787040B0FAB

I know you won't believe me, but the highest form of Human Excellence is
to question oneself and others. -- Socrates
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 195 bytes
Desc: not available
URL: <https://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20240129/3b307a1d/attachment.sig>