[libcamera-devel] versioning

[Laurent Pinchart]

Hello,

On Sun, Aug 14, 2022 at 06:01:43PM +0100, Kieran Bingham via libcamera-devel wrote:
> Quoting Christian Rauch (2022-08-14 17:25:48)
> > Am 14.08.22 um 16:12 schrieb Kieran Bingham:
> > > 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?

As I see it, the main reason to tag releases, from a distribution point
of view, is to increase the SONAME of the library. This will prevent
binaries linked against one version of libcamera to run with an
incompatible version. This can probably be done without modifying
meson.build, based on a similar mechanism as gen-version.sh. The project
version (in the root meson.build file) and the libcamera shared library
version can also be generated through a similar mechanism, using
run_command() directly in the project() function call for the former as
the project() function must be called before anything else. See
https://gitlab.freedesktop.org/mesa/mesa/-/blob/main/meson.build for
instance.

Until we tag v1.0, we should use the ABI version as the SONAME. Ideally,
I'd like to use libcamera.so.0.X as the SONAME for now, not
libcamera.so.X, to allow using libcamera.so.1 once we release v1.0. I
don't know if that's a valid SONAME though.

Automatic ABI breakage checks is nice to have, but I don't think it's a
strict requirement to tag anything. We can start with a time-based
tagging scheme (weekly for instance), with v0.0.X where X will be an
increasing index. Once ABI checks are in place, this could become
v0.X.Y. The exact versioning scheme doesn't matter much to me, as long
as it doesn't corner us for the v1.0 release.

Kieran, if you'd like to implement now a weekly release scheme that
would use the latest tag or the .tarball-version file to populate the
project version, library version and SONAME using a v0.0.X versioning
scheme without ABI checking, I'll review the patches.

> > I have seen CMake projects generating the version information from git.
> > This somehow works that a git command is executed as part of the build
> > process and then the stdout is parsed. Of course, this only works when
> > the source is checked out as a git repo. But I think something similar
> > could be done in meson. Then, you only need to create a new git tag and
> 
> We already do this.
> 
> https://git.libcamera.org/libcamera/libcamera.git/tree/meson.build#n13
> 
> meson calls utils/gen-version.sh which generates a version string such
> as :
> 
>   0.0.0+3829-f88d73af
> 
> But it only works when the source is checked out as a git repo indeed.
> 
> How does that compare for your current needs against the discussions
> above?
> 
> > the next time libcamera is compiled, it would generate the version.
> > 
> > >> 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.

-- 
Regards,

Laurent Pinchart