[libcamera-devel] versioning

[Christian Rauch]

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
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
>>>>