Subject: Interface stability guarantees

From: Robert Ancell <[email-masked]>
Date: Mon, 12 Aug 2013 16:26:28 +1200

Hi,

We have a number of interfaces we're maintaining in Mir, with differing
levels of interface stability.

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.

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.

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

--Robert

[1] https://developers.google.com/protocol-buffers/docs/proto#updating

---

From: Oliver Ries <[email-masked]>
Date: Mon, 12 Aug 2013 11:21:46 -0600

On Sun, Aug 11, 2013 at 10:26 PM, Robert Ancell <[email-masked]
> wrote:
[...]

> 6. Rebuild any dependencies on libmirclient1 (currently xorg-server, mesa
> - this list will only get bigger over time).
>
> 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.

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

> bumping the so version would slow us down (we would be libmirserver1000 by

best,
Olli