Versioning interfaces

[Daniel P. Berrange]

On Mon, Nov 14, 2005 at 12:20:10PM +0000, Robert McQueen wrote:
> Havoc Pennington wrote:
> > Historically my thought on that has been to just use the COM rule (if
> > you change an interface you rename it). I think the COM rule is probably
> > right for *breaking* an interface at least...
> 
> This is reasonable, I'm not too keen to waste time arguing it. :)

Much as I hate to further open a can of worms when we're so close to 1.0, this 
idea of interface renaming when breaking API doesn't seem to particularly nice
consequences 

Thinking about the implications of applying the rule in a real app - say there 
is an interface defining the API contract for a music player with the name of 
'org.example.Music.Player'. Now with a new release, the API is broken for whatever 
reason, so the interface has to be renamed - how should a new name be chosen ?

 a) Think of some synonym for 'Music Player', perhaps deciding to rename 
    to something like 'org.example.Audio.Player'. 

 b) Just tack a number onto the end of the interface name, getting
    something like  'org.example.Music.Player2', 'org.example.Music.Player3',
    etc, etc.

 c) Don't bother renaming the interface at all

 d) Something else ?

Option a) is clearly not viable in long term, because one quickly run out of
sensible synonyms to use as names & given a pair of arbitrary interface names, 
there's no way to tell at a glance which interface is 'newer'. Option b) just
plain sucks, because it is defacto encoding versioning info in the interface 
names - where its completely opaque to any versioning resolution logic. In
reality many apps will choose c), even though it is truely evil. 

I don't think any of these three outcomes are particularly desirable, thus
unless there is an awesome option d) i've not thought of, I can't help be
think we need to do a more explicit versioning scheme. Major/minor pair,
arbitrary levels of '.' separated digits x.y.z/x.y.z.a, or perhaps just
follow the libtool 'CURRENT:AGE:REVISION' versioning scheme [1]. 

> > for adding more methods to
> > an interface, maybe the versioning is a better approach but here's an
> > idea I just had: rather than an explicit version, the "version" is just
> > a count of the number of methods and signals the interface has. So if
> > you add stuff, the version automatically goes up. It can't go down,
> > since to break an interface you have to rename it. If you want to be
> > sure you have all the methods you expect, you just require that the
> > interface member count is at least what it is today.
> 
> It took me a long time to realise why this wouldn't work (nobody else
> does versioning this way), but when redrafting the interface
> specification for our project yesterday, I realised the problem.
> Counting interfaces/signatures does not take account of when you add
> functionality to an existing method in another direction, such as making
> a previously invalid input (a new enum constant) valid. Between version
> 1.1 and 1.2 of an interface, the methods might not change necessarily,
> but a new constant FOO_BAR_STATE is added which can now be understood by
> the methods or emitted in signals. Or something like that.


Regards,
Dan.

[1] http://ftp.gnu.org/gnu/Manuals/libtool-1.4.2/html_node/libtool_34.html
-- 
|=-            GPG key: http://www.berrange.com/~dan/gpgkey.txt       -=|
|=-       Perl modules: http://search.cpan.org/~danberr/              -=|
|=-           Projects: http://freshmeat.net/~danielpb/               -=|
|=-   berrange at redhat.com  -  Daniel Berrange  -  dan at berrange.com    -=|
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://lists.freedesktop.org/archives/dbus/attachments/20051114/dff7b1ae/attachment.pgp