[FFmpeg-devel] [RFC] Internal API updating policy

[Uoti Urpala]

On Sat, 2010-05-15 at 22:47 +0200, Stefano Sabatini wrote:
> I propose to follow these rules:
> 
> * bump minor/micro number when adding an internal or public symbol,
>   renaming one of them, or changing the order of parameters of an
>   internal function
> 
> * bump the minor/micro number of a library when it starts to depend on
>   a symbol defined in another (internal) library, or that symbol
>   changed (e.g. it was renamed or the corresponding function changed
>   signature).
> 
> This should help to track the internal libraries dependencies
> (e.g. lavc-X.Y.Z depends on lavu >= A.B.C and lsws >= D.E.F).

This is not enough to make things really work. See
http://lists.mplayerhq.hu/pipermail/ffmpeg-devel/2010-January/081635.html

Changes to "internal" symbols used by other FFmpeg libraries require a
major version bump and soname change, at least if the dependency already
existed in a previous major version of the depending library and the
depended-on library has not changed soname later.

> If an internal symbol is renamed at lavc X.Y.Z, and lavf uses that
> symbol, then the minor/micro of lavf should be bumped and we would
> have the dependency:
> lavf A.B.C depends on lavc >= X.Y.Z

This is the part that of your suggested rules that can fail. Suppose
lavf major version 1 already uses that symbol, and current lavf version
is 2. Both use lavc version 1. Having both lavf1 and lavf2 installed
simultaneously must be possible. You can't update lavf1 because there
are no newer versions of it, and it would be incompatible with the
changed lavc, so it must depend on lavc1 < X.Y.Z. OTOH lavf would depend
on lavc1 >= X.Y.Z. Therefore the version of lavc1 installed would need
to satisfy both that the version is < X.Y.Z and >= X.Y.Z. This is
impossible, so package version constraints aren't enough and a major
lavc version bump is required.

> Another good idead would be to document such dependencies in
> APIchanges, thus simplifing distro packagers work.
> 
> As for what regards applications depending on the internal API, I
> don't think there is some way to avoid their breakage and they should
> really avoid that sort of dependencies (and possibly collaborate with
> us if they really think the API they're using should be made public),
> but having such a system for tracking the internal API changes should
> help the packagers to define their dependencies with the FFmpeg
> libraries.

I agree with the application part, and have changed MPlayer in git to
only use public symbols by default. But it's important to realize that
the current versioning/dependency handling _within FFmpeg_ is not fully
safe whatever applications do.