Interface stability guarantees

[Robert Ancell]

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/mir-devel/attachments/20130812/88853380/attachment.html>