preparing new RtMidi release, question about SO version

[Stephen Sinclair]

Thanks very much Felipe, that clarifies things immensely.

A last question, is there a difference between using this -release
style versioning and simply bumping the SO name on every release?

In any case, I'll keep these recommendations in mind for all my
projects (which for some reason always seem to be libraries.. god...
:P), thanks.

Steve


On Mon, Feb 15, 2016 at 7:44 PM, Felipe Sateler <fsateler at debian.org> wrote:
> On 15 February 2016 at 16:38, Stephen Sinclair <radarsat1 at gmail.com> wrote:
>> On Mon, Feb 15, 2016 at 12:05 PM, Felipe Sateler <fsateler at debian.org> wrote:
>>> Hi Stephen
>>>
>>> On 10 February 2016 at 14:21, Stephen Sinclair <radarsat1 at gmail.com> wrote:
>>>>
>>>> Hello,
>>>>
>>>> I am helping to update RtMidi, a C++ class for cross-platform MIDI
>>>> support.  There is a Debian librtmidi package.  Although this is just
>>>> a bug-fix release, and is planned to go from 2.1.0 to 2.1.1, we have
>>>> added some automake/libtool infrastructure, and a last debate is
>>>> whether to properly start supporting SO version according to libtool's
>>>> rules.
>>>
>>> Cool. I would be careful, though, because for C++ seemingly innocent
>>> changes can break the ABI. STK[1] was recently updated to use
>>> libtool's -release style versioning to avoid problems, as some changes
>>> broke ABI and were not noticed by upstream as such. This is
>>> particularly important for libraries that are used as static libraries
>>> (as this kind of breakage might go unnoticed for a  while).
>>
>> So that's sort of part of my question -- I'd like to integrate better
>> ABI testing into the usual procedure, so as to avoid changes that
>> "were not noticed by upstream."  If such problems are more likely
>> noticed by packagers, would it be good practice to always request a
>> pre-release review by packagers before doing an upstream release?  Or
>> would that be too much noise?  (Not that releases are done very
>> often.. but I'm asking in the general case, I'll likely apply this as
>> a rule of thumb to other software I maintain.)
>
> Well, I'm not sure packagers do anything special. We do have symbols
> files that can help, but those are not currently in use by rtmidi (in
> c++ in general they can be a bit of a pain). There are external tools
> that can help (like the
> abi-{compliance-checker,monitor,viewer,tracker} tools), but I think
> the main way to keep this is to do it pre-emptively: be aware of
> changes that can change ABI and do not merge those. For C++, this is
> quite limiting, though[1]. ABI stability of C++ libraries is hard.
>
>
> [1] https://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C%2B%2B#The_Do.27s_and_Don.27ts
>
>>
>>> [1] https://github.com/thestk/stk/pull/27
>>>>
>>>> Previous versions have made the error of treating SO version like the
>>>> version number, and producing binaries e.g. librtmidi.so.2.1.0.
>>>>
>>>> I was recommending changing this to properly reflect ABI
>>>> compatibility.  What would Debian maintainers prefer here?
>>>
>>> If (and only if) proper ABI versioning can be done, then I'd prefer
>>> that, of course. But using a -release style versioning would also be
>>> ok, and force rebuild of all reverse depedends on each upstream
>>> version. This should be ok, as there aren't many (6 by my count). This
>>> has the advantagae for upstream that they do not have to care about
>>> abi.
>>
>> I don't think it's a huge overhead to check for ABI changes between
>> releases, provided this can be done (largely) automatically.  Which
>> should be possible, although I haven't explored the available tools
>> yet.  I'm not 100% sure what you mean by -release style versioning.
>> You mean append the library version as if it were the SO name?
>> Doesn't that lead to complications when there's a bugfix release that
>> happens to change the ABI? Or rather you seem to be suggesting a full
>> SO bump on every release.  I'm not sure if I follow.
>
> Yes, I suggest a full bump on every release. That, while not optimal
> from a downstream perspective, is still manageable, and is much more
> convenient for upstream and less error-prone.
>
> Note that -release style versioning is setting SONAME as
> libfoo-x.y.z.so instead of libfoo.x
>
>>
>>>> I proposed making the new SO version 3.0.0, to really emphasize that
>>>> the ABI version is new, however since it's a bugfix release I don't
>>>> know if that's the recommended strategy.
>>>>
>>>> https://github.com/thestk/rtmidi/pull/59
>>>>
>>>> In any case I notice that the interface has changed a bit, e.g. some
>>>> functions have lost parameters, others have new parameters, since the
>>>> last release.
>>>
>>> I see the pull request has already been merged. I hope this message
>>> doesn't come too late.
>>
>> Yes, the release has been done.  However, I think bumping the SO name
>> was the right call, seeing as the ABI signature of setErrorCallback()
>> changed.  I just figured we may as well use it as an opportunity to
>> make it significantly different from the release version while we're
>> at it.
>
> I agree a bump was required.
>
> In summary:
>
> 1. C++ ABI compatibility is hard.
> 2. If you can (as upstream) commit to ABI stability and manage it,
> this is the best for downstreams.
> 3. If you cannot, then I find -release style versioning acceptable as
> well. While it is inconvenient to have to rebuild all reverse
> dependencies, it beats having to figure out weird crashes when library
> versions don't match.
>
>
>
>
> --
>
> Saludos,
> Felipe Sateler