Versioning issues

[dariusz-f]

This issue is related to the latest changes in OpenAPV code and long discussions about project versioning.

At this moment we're in some kind of deadlock and we cannot proceed further with OpenAPV integration due to different versioning requirements, so we need to make agreement among project maintainers and FFmpeg community to go further with common plans related to OpenAPV.

Integrations Background

OpenAPV in already integrated with:

• latest Android 16 Beta (code freeze)
• some 3rd-party chip vendors (hardware, so cannot be easy change)

Ongoing integrations:

• ffmpeg (already integrated OpenAPV encoder)

The problem!

In OpenAPV project we made some changes in versioning mechanism #91 but this is not complete implementation and it brings new issues:

• Android build problem due to different build system (not cmake but soong)
• Introduction of two versions (project and library) which causes a lot of collateral damage

From the other hand FFmpeg require clean rules and information related to OpenAPV library (.so file) to know when API is changed and backward compatibility is broken #96 #97. This is crucial to proceed further with OpenAPV decoder integration with FFmpeg.

Required action

We need together to make an agreement, how versioning mechanism need to work and what can be changed now due to current constrains.
So my proposition is to discuss in this issue common statement related to whole versioning mechanism and next implement based on that this what can be done in this moment (fix issues, revert #91, find another solution).

As I said before this is crucial to proceed further with integration so we need to solve this!
We already wasted two weeks on this problem due to not have a common statement.

Involved people

OpenAPV maintainers: @kpchoi @tuzm24 FFmpeg community: @jamrial and integration devs: @dkozinski @dariusz-f

Please share your opinion about this problem and discuss how we need to change versioning to satisfy everyone involved.

[jamrial]

Introduction of two versions (project and library) which causes a lot of collateral damage

What is the collateral damage?

As for the arguments in favor of the split, the soversion needs to reflect the contents of the library (symbols, binary offsets, etc), and unless the project version (which again is, or should be, cosmetic and arbitrary) is intended to be increased every time such a change happens, then it needs to be independent. And seeing that project version is tied to a tagged release, that doesn't sound like a good idea.
The split should present absolutely no issue to applications compiling and liking against any given tagged release, and will ensure binary backwards compatibility between releases (no need to relink, which is something distros will appreciate) if major soversion doesn't change between them.

[dariusz-f]

Collateral damage is a problem with users that already integrated OpenAPV and they relay on current versioning mechanism which is only one common version.

So for now we can't change project versioning to introduce separate versions for project and lib.
Unfortunately we will have to refactor versioning code and eventually revert some latest changes.

We try to fit to all library users, but introduction separate versions is very problematic so we will follow this scheme: API_SET.MAJOR.MINOR.PATCH

@jamrial can you summarize what versioning rules FFmpeg require from us?

Next we will check what can be done at this moment.

[jamrial]

Collateral damage is a problem with users that already integrated OpenAPV and they relay on current versioning mechanism which is only one common version.
So for now we can't change project versioning to introduce separate versions for project and lib.

Can you explain how does this affect existing integrations?

I assume that right now they are fetching the v0.1.13 tag, and compiling it. They then link their applications to liboapv.so, which is a symlink to liboapv.so.0. They are also probably looking at pkg-config for a version >= 0.1.13 (or lower?) to do this.
None of these are affected by the existing implemented changes, nor the proposed ones in #97.

Given the fact there were no version defines in any installed header prior to the recent changes (Thus none are present in any tagged release), they rely 100% on compile time checks, namely, whatever pkg-config says is present in their toolchain. So i don't see how their current reliance on the old versioning mechanism is affected at all. The old versioning mechanism was barely even communicated at all.

If you want to make the minimum amount of changes in #97 while still introducing the versioning changes meant to allow for proper distro deployment, then make it so pkg-config keeps reporting package version and not library version, then rollback the major soversion to 0 (Ensuring all symbols and struct field offsets are the same as they are in the v0.1.13 snapshot, which means no changes to the existing oapv_version() signature), and set minor to the same value it was before the recent changes, or to a higher one if new symbols are introduced (like oapv_libversion()).
That way, short of a real need for an ABI breaking change, existing implementations will be able to compile oapv from git head and see no difference even if they don't re-link their applications (Drop-in binary compatibility).

[jamrial]

@jamrial can you summarize what versioning rules FFmpeg require from us?

What ffmpeg needs is for a library to follow Semantic Versioning, at least the major and minor version parts. Said versions should be defined in a public header as well as reflected in the soversion, so pre-processor checks can be added to support newly introduced API from several revisions while keeping the minimum supported one being the oldest possible.

[dariusz-f]

All is clear in this topic, we can close the issue now.