[libcamera-devel] versioning

[Kieran Bingham]

Quoting Christian Rauch via libcamera-devel (2022-08-14 22:26:38)
> Hi Kieran,
> 
> Am 14.08.22 um 19:01 schrieb Kieran Bingham:
> > Quoting Christian Rauch (2022-08-14 17:25:48)
> >> Hi Kieran,
> >>
> >> Am 14.08.22 um 16:12 schrieb 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?
> >>
> >> 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?
> 
> I overlooked that, but this is generally how I've seen this in CMake.
> But the git repo does not have version tags yet, so there is nothing to

Really? It should.

kbingham at Q:/tmp$ git clone https://git.libcamera.org/libcamera/libcamera.git
Cloning into 'libcamera'...
remote: Enumerating objects: 31196, done.
remote: Counting objects: 100% (31196/31196), done.
remote: Compressing objects: 100% (11093/11093), done.
remote: Total 31196 (delta 24129), reused 26079 (delta 19945)
Receiving objects: 100% (31196/31196), 5.65 MiB | 7.29 MiB/s, done.
Resolving deltas: 100% (24129/24129), done.
kbingham at Q:/tmp$ cd libcamera/
kbingham at Q:/tmp/libcamera$ ./utils/gen-version.sh
0.0.0+3830-dfc6d711

kbingham at Q:/tmp/libcamera$ cd ..
kbingham at Q:/tmp$ rm -rf libcamera/
kbingham at Q:/tmp$ git clone https://git.linuxtv.org/libcamera.git/
Cloning into 'libcamera'...
remote: Enumerating objects: 31197, done.
remote: Counting objects: 100% (31197/31197), done.
remote: Compressing objects: 100% (6802/6802), done.
remote: Total 31197 (delta 24237), reused 31197 (delta 24237)
Receiving objects: 100% (31197/31197), 5.84 MiB | 5.37 MiB/s, done.
Resolving deltas: 100% (24237/24237), done.
kbingham at Q:/tmp$ cd libcamera/
kbingham at Q:/tmp/libcamera$ ./utils/gen-version.sh
0.0.0+3829-dfc6d711

Are you using one of the official sources above? I've just seen that my
personal fork on github doesn't have a tag, so I'll update it there.

> extract. The *.pc file ("libcamera.pc") just contains "Version: 0.0.0".

> > Kieran
> >
> >
> >> 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.
> >>>
> >>> --
> >>> Kieran
> >>>
> >>>
> >>>> Best,
> >>>> Christian
> >>>>