<div dir="ltr">On Sun, Aug 11, 2013 at 10:26 PM, Robert Ancell <span dir="ltr"><<a href="mailto:robert.ancell@canonical.com" target="_blank">robert.ancell@canonical.com</a>></span> wrote:<div>[...]<div class="gmail_extra">
<div class="gmail_quote"><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div><div>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):<br>

</div><div>1. Update MIRCLIENT_ABI in src/client/CMakeLists.txt<br></div><div>2. Rename debian/libmirclient1.install to debian/libmirclient2.install<br></div><div>3. Change libmirclient.so.1 to libmirclient.so.2 in debian/libmirclient2.install<br>

</div><div>4. Change references to libmirclient1 to libmirclient2 in debian/control<br></div><div>5. Update any references to this package in doc/*<br></div><div>6. Rebuild any dependencies on libmirclient1 (currently xorg-server, mesa - this list will only get bigger over time).<br>

</div><div><br></div><div>What happens for the archive admins:<br></div><div>1. They see a new package that have to approve (libmirclient2)<br></div><div>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.<br>
</div></div></div></blockquote><div><br></div><div>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. </div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div><div>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.<br>
</div></div></div></blockquote><div><br></div><div>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. </div>
<div><br></div><div>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.</div>
<div><br></div><div>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.</div><div><br></div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div><div>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.<br>

</div><div><br></div>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).<br>
</div></div></blockquote><div><br></div><div>best,</div><div>Olli</div></div></div></div></div>