[FFmpeg-devel] [PATCH 3/3] doc/developer.texi: add a section on API/ABI compatibility

[Anton Khirnov]

Just FYI I've already pushed these patches, but I appreciate the
comments anyway.

Quoting Stefano Sabatini (2023-03-20 23:26:11)
> On date Wednesday 2023-03-15 15:07:46 +0100, Anton Khirnov wrote:
> > Document established practices in it.
> > ---
> >  doc/developer.texi | 162 ++++++++++++++++++++++++++++++++++++++++-----
> >  1 file changed, 146 insertions(+), 16 deletions(-)
> > 
> > diff --git a/doc/developer.texi b/doc/developer.texi
> > index 5e283227be..c625a9feed 100644
> > --- a/doc/developer.texi
> > +++ b/doc/developer.texi
> > @@ -217,6 +217,7 @@ int myfunc(int my_parameter)
> >  ...
> >  @end example
> >  
> > + at anchor{Naming conventions}
> >  @section Naming conventions
> [...]  
> > +
> > + at anchor{Major version bumps}
> > + at subsection Major version bumps
> > +A major version bump signifies an API and/or ABI compatibility break. To reduce
> > +the negative effects on our callers, who are required to adapt their code,
> > +backward-incompatible changes during a major bump should be limited to:
> > + at itemize @bullet
> > + at item
> > +Removing previously deprecated APIs.
> > +
> > + at item
> > +Performing ABI- but not API-breaking changes, like reordering struct contents.
> > + at end itemize
> > +
> 
> This sounds a bit ambiguous. What qualifies "previously deprecated
> APIs"? It looks to me that the current practice is to drop deprecated
> symbols after 2 major bumps, so that users have the opportunity to
> adapt their code depending on the deprecations warnings before the
> deprecated symbols are finally removed at the next bump. If that's so,
> maybe this can be formalized here.

The ambiguity is actually deliberate, because I know different
developers have different opinions on what the criterium should be
exactly, and I did not want this whole new text to be bikeshud to death
because of this. My plan was to push this text with ambiguous wording,
and then later add a precise rule.

The previous "consensus rule" was to remove APIs after they've been
deprecated for two yeas, but in recent developer meetings it was
universally agreed that time-based rules do not make sense. The main
alternative suggestions that I remember is that a major bump removes
things that were deprecated in X previous major releases (I'm personally
in favor of this with X=2).
Other suggestions, along with arguments for why they are the obviously
correct choice, are very much welcome.

-- 
Anton Khirnov