Interface stability guarantees

[Oliver Ries]

On Sun, Aug 11, 2013 at 10:26 PM, Robert Ancell <robert.ancell at canonical.com
> wrote:
[...]


> libmirclient is a stable interface. If you make any changes that remove
> functionality then you need to bump the so version. You can add new
> functionality without penalty. The process for bumping the interface is
> (e.g. libmirclient1->2):
> 1. Update MIRCLIENT_ABI in src/client/CMakeLists.txt
> 2. Rename debian/libmirclient1.install to debian/libmirclient2.install
> 3. Change libmirclient.so.1 to libmirclient.so.2 in
> debian/libmirclient2.install
> 4. Change references to libmirclient1 to libmirclient2 in debian/control
> 5. Update any references to this package in doc/*
> 6. Rebuild any dependencies on libmirclient1 (currently xorg-server, mesa
> - this list will only get bigger over time).
>
> What happens for the archive admins:
> 1. They see a new package that have to approve (libmirclient2)
> 2. They have an old package that can no longer be built (libmirclient1).
> If you haven't done all of step 6 then this can't be removed from the
> archive until everything is rebuilt.
>

thanks for sharing these steps Robert. I would also like to suggest that it
is good practice of letting your archive admin (didrocks) know upfront so
he can plan for the additional work.


> So what I'm trying to say is think twice before bumping the so version, it
> has a number of side-effects :) Where possible, mark old functions as
> deprecated and add new ones. Every now and then (e.g. near an Ubuntu
> release) we can drop a bunch of deprecated functions in one so version bump.
>

I'd also like to point out that we need to be considerate of potential
non-Canonical/Ubuntu consumers of the API. I understand that this is less
of an issue right now as we are not too many consumers, but as we are
trying to increase the Mir userbase API/ABI stability needs to be a focus.

One feedback from conversations with our technology partners is that they
are actually looking into this issue already right now and we (Kevin,
Thomas, myself) receive questions around API/ABI stability plans.

IOW (and as mentioned by Robert below in the Libmirserver1000 example)
starting on 8/29 (13.10 Feature Freeze) we (i.e. you ;) need to do a great
job here, to manage these changes well.

The Mir client binary protocol uses Google protocol buffers and if managed
> correctly can be both forwards and backwards compatible [1]. Since there is
> nothing to stop and old libmirclient connecting to a new Mir server we need
> to be backwards compatible. Since we're still iterating this interface
> quite a bit we're not worrying too much if the behaviour changes for old
> client, but this is a luxury we won't be able to do forever.
>
> libmirserver is an unstable interface. Any software that uses this library
> should depend on the exact version of the library it was compiled against
> and be rebuilt when libmirserver changes. Currently, that is
> unity-system-compositor and unity-mir and the daily landing system takes
> care of this rebuilding for us. There is code in Mir's debian/rules that
> ensures anything built against libmirserver depends on the exact package
> version so they can't get out of sync. The current so version is 1, and it
> should remain until we become stable. We're not stable at the moment
> because the cost of having to remain backwards compatible or constantly
> bumping the so version would slow us down (we would be libmirserver1000 by
> now).
>

best,
Olli
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/mir-devel/attachments/20130812/371d2d04/attachment.html>