Add SOVERSION for the C++ libraries

[darbyjohnston]

Related to #872 and #1182, but this is just for the C++ libraries.

This change sets the SOVERSION for the C++ libraries. This version should be incremented anytime the ABI changes. OTIO is currently using the minor version number for breaking changes, e.g. v0.15, v0.16.0, v0.17.0, so SOVERSION is set as a combination of OTIO_VERSION_MAJOR and OTIO_VERSION_MINOR. When OTIO reaches version 1.x.x then SOVERSION could be changed to track just OTIO_VERSION_MAJOR.

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 84.72%. Comparing base (c0e97b0) to head (640377f).
Report is 51 commits behind head on main.

❌ Your changes status has failed because you have indirect coverage changes. Learn more about Unexpected Coverage Changes and reasons for indirect coverage changes.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1860      +/-   ##
==========================================
+ Coverage   84.11%   84.72%   +0.61%     
==========================================
  Files         198      177      -21     
  Lines       22241    12809    -9432     
  Branches     4687     1191    -3496     
==========================================
- Hits        18709    10853    -7856     
+ Misses       2610     1773     -837     
+ Partials      922      183     -739     

Flag	Coverage Δ
py-unittests	84.72% <ø> (+0.61%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

see 131 files with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 4d31e15...640377f. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[darix]

TBH: using the version number for the SO version is a good starting point and bumping with the version is an easy way to avoid problems.

but there is actual tooling now for understand when you need to bump your soversion. e.g. libabigail.

https://media.ccc.de/v/1234-libabigail-how-semantic-analysis-of-c-and-c-elf-binaries-can-be-used-to-analyze-abi-changes

[meshula]

I propose the following policy to make the policy concrete

The SO version must be incremented every time a change occurs to the ABI that causes a backward incompatibility. Such changes include, exhaustively:

• a change to struct or class layout
• enum changes that would cause a renumbering of previously published enums
• a removal of a struct, class, enumeration, or function
• a change in parameters to a free standing function
• a removal of a global variable

OTIO currently designates the minor version number for breaking changes, e.g. v0.15, v0.16.0, v0.17.0, accordingly the SOVERSION will be incremented to match. SO version must be monotically increasing, so the ABI version should be computed as major100 + revision1. The third digit will never implicate an ABI version change.

Distros that wish to minimize version changes are encouraged to pick the version of OpenTimelineIO that was released most recently before the last cut off date of the most recent vfxplatform year. Distros that wish to always be on head are advised that ABI version is considered carefully before a bump and subject to OpenTimelineIO project policy.

[JeanChristopheMorinPerso]

@meshula I find the following confusing:

Distros that wish to minimize version changes are encouraged to pick the version of OpenTimelineIO that was released most recently before the last cut off date of the most recent vfxplatform year. Distros that wish to always be on head are advised that ABI version is considered carefully before a bump and subject to OpenTimelineIO project policy.

I'm curious, why mention the vfxplaform? Also, why does picking a version released before the latest VFX platform year minimize changes?

As for the last statement, it might be just because I'm not a native English speaker, but I find it confusing. Is the intent to say that the head isn't yet stabilized and can't be relied on, ABI wise?

[darix]

target platform shouldnt have any impact on when to bump the soversion. the important bit is when you break the ABI.

that's why I suggest using tools like abigail over guessing. :)

[meshula]

I'm curious, why mention the vfxplaform? Also, why does picking a version released before the latest VFX platform year minimize changes?

Distros that wish to minimize version changes are encouraged to pick the version of OpenTimelineIO that was released most recently before the last cut off date of the most recent vfxplatform year. Distros that wish to always be on head are advised that ABI version is considered carefully before a bump and subject to OpenTimelineIO project policy.

That's PTSD from OpenEXR/Imath and distros trying to slice and dice an old OpenEXR (2.x) with a new Imath (3.x) . Maybe we don't need the advice; if people run into problems with the Imath dependency they should use the interred version, and maybe we don't need to say anything about that.

As for the last statement, it might be just because I'm not a native English speaker, but I find it confusing. Is the intent to say that the head isn't yet stabilized and can't be relied on, ABI wise?

No, now that you've asked me to think more carefully about my comment, it's meant to say if you are building an old vfxplatform and you want to use system Imath, you should pick an OTIO from the vfxplatform year you care about, otherwise you might run into Imath2/3 problems.

Again, maybe Imath2 is gone by now, so maybe not worth caring about.

[darbyjohnston]

@meshula I updated the comments with your feedback, and also added some examples of release versions and their corresponding ABI versions. I left out the parts about the distros, hopefully moving to Imath3 will sort that out. When you have a chance take a look and see what you think.

[meshula]

lgtm