[libcamera-devel] versioning

[Kieran Bingham]

Hi Christian,

Quoting Christian Rauch via libcamera-devel (2022-08-13 22:14:44)
> Hi all,
> 
> I am aware that the libcamera API is unstable and because of this, there
> is no versioning. I am using libcamera in another project, and it would
> be helpful if I could check some version constraints in order to prevent
> compiling with an incompatible API.

I've been long advocating that we should have a version number, even
with an unstable API. The last time I tried to push on this topic we
added 0.0.0 at the very first commit which gives us some degree of
patchlevel versioning for every commit.  It has taken a long time to
identify clear reasons /why/ we should have more specific versions, when
we have a clear unstable API, and we refer to the latest.

However as you have reported here, with more API breakages recently -
having other pacakges compiling against libcamera, they likely want to
check what is installed. It's not always under the control and can
depend upon the installation of the distro.


> Would you be willing to start versioning the minor or patch-level of
> libcamera? I imagine that the major version will stay at "0" until the

I believe the answer is 'yes' now. But we still need to implement the
'how'.

Personally - I would like to use something like abi-compliance-checker
to automatically detect any ABI/API change, and automatically increment
the minor patch level. libabigail looks interesting and relevant too:
https://developers.redhat.com/blog/2020/04/02/how-to-write-an-abi-compliance-checker-using-libabigail#

That would give us a version scheme of:

 0.a[bp]i.patch

Where other packages and applications could then use the second value to
determine if they are compatible, (or to make conditional changes to be
compilation compatible).

The patch level of course would just be the number of patches since that
change, and the leading version 0, would not be incremented until we
were at a point that we could be comfortable stating we are 'ABI stable'.


> API is stable, but that either the minor or patch-level could be
> incremented (0.1, 0.2, ...) every time the API changes, or simply on a
> monthly or quarterly basis.

Every time I've suggested we should start making release versions, I
always face push back of "What decrees a release, when should it be
made?".

To me time based milestones are acceptable, but don't make it
easy/straightforwards to perform the version specific compilation
changes required.

I think they help users understand how new or old the library is though,
and at least that is more helpful than our current versioning scheme
where comparing 074fa98ac4e against 18d61deb3c0 is just not human
readable, and doesn't convey any useful information. We have tagged our
first commit as 0.0.0 which does now at least provide version strings
generated by utils/gen-version.sh:

 - 0.0.0+2819-18d61deb
 - 0.0.0+3459-074fa98a

So we could already say we could (manually) identify API/ABI changes
between the patch level numbers after the + (2819, to 3459) - but that's
quite labour intensive otherwise and prone to error, which is why I'd
really like to see API/ABI breakages identifiable through something like


 - 0.25.245-18d61deb
 - 0 29.15-074fa98a

Which we can then parse and extract more useful information from.

I would envisage the automatic abi checker to be able to provide the
0.<abi> tags automatically on every change if run on every commit (and
could be back dated right to the beginning of the tree history) ...
however the point I have difficulty with is how we get those tags to
then convey the correct information about the release in external
systems.

Is a 'tag' sufficient? or do we have to (for every 'release') manually
edit the meson.build version string, or make other manual explicit
changes.

If we can do something around simply adding a tag on every abi/api
version change, - I think that would provide the cleanest/simplest way
forwards for now.

Any ideas or extended comments?


> This way, projects could check for a specific version before compiling
> or search for a specific "API version". It wouldn't guarantee that the
> API is compatible between versions, it's just useful to know which
> version you have to use to compile a project.

Agreed!

It's also clear from other recent discussions that we should bump the
SONAME for every ABI breakage, so again - if this can be handled through
automatically detecting those breakages - I think that would help too.
Having the SONAME as 0.<abi-version> as above would be a great benefit
already I think.

--
Kieran

 
> Best,
> Christian
>