[libcamera-devel] versioning

[Eric Curtin]

On Mon, 15 Aug 2022 at 13:05, Laurent Pinchart
<laurent.pinchart at ideasonboard.com> wrote:
>
> Hi Eric,
>
> On Mon, Aug 15, 2022 at 12:59:47PM +0100, Eric Curtin wrote:
> > On Mon, 15 Aug 2022 at 06:29, Laurent Pinchart via libcamera-develwrote:
> > > On Sun, Aug 14, 2022 at 11:44:05PM +0200, Christian Rauch via libcamera-devel wrote:
> > > > Hi Laurent,
> > > >
> > > > I think the SONAME is not the primary reason for tagging/versioning.
> > > > Having API versions is mainly used to check compatibility for other
> > > > projects. That means that the version information has to be encoded in
> > > > some project file, e.g. *.pc files. Using a SONAME is really just useful
> > > > if you want to have multiple versions of a library installed or if you
> > > > want to make sure that you only link a specific version.
> > >
> > > Bumping the SONAME is a requirement from distributions when a new
> > > version breaks ABI compatibility, so I think this is very important. It
> > > will also help avoiding users facing bugs due to incompatibilities
> > > between the version an application was compiled against and the version
> > > installed on the system.
> >
> > This is very important. I also am not the biggest fan of automating
> > the version number bumping against a git mechanism. I have worked on
> > projects like this and although it is convenient it is not ideal for
> > package maintainers amongst other use cases like building against a
> > tarball, etc. Fedora/EPEL are one such example where you upload the
> > sources, you are not connected to the real origin repo directly at
> > all.
>
> Note that we generate a .tarball-version file when running `meson dist`.
> Would that help ?

I think this is ok, sorry for the delayed response.

>
> > So I would propose manual bumps when required and not tie specifically
> > to the version control system.
> >
> > > In any case, we can version both the project, the library, and the
> > > SONAME without extra complexity.
> > >
> > > > Am 14.08.22 um 21:01 schrieb Laurent Pinchart:
> > > > > 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
>