bzrlib version compatability support

[Robert Collins]

On Wed, 2007-06-06 at 11:04 -0500, John Arbash Meinel wrote:
> 
> I'm curious how the helper in bzrlib should look like. So far I see:
> 
> 1) Ability to check whether the versions match, and issue a warning if
> there is
> a problem.

I think raising an exception is the right thing. it should be a UI one
and formatted to show the right error. Plugins that want to warn rather
than fail when the versions are not compatible may want a wrapper
function to support that.

> 2) Ability to not warn if the versions are "close" and both sides are
> "dev"
> versions.

uhhh. I don't get this. Do you mean 'or both sides are dev versions' ?

> 3) Some way of manually disabling the warning, possibly for a specific
> plugin +
> version pair. (Or maybe just disabling them altogether). (For users
> who know
> that 0.17 is compatible with 0.18, and would you please stop annoying
> me TYVM) 


I think in bazaar.conf:
disable_plugin_version_checks=PLUGINSLIST

is simple and probably good enough.

Interface versioning
====================

In terms of version matching, I'd like to propose the following:

 * plugins are compatible with bzrlib ABI's.
 * bzr exports an overall ABI in terms similar to libtools
 * plugins export an ABI themselves for other plugins to use.
 * optionally: bzr exports minor ABI's for individual areas of the
library.

In libtool an ABI is expressed by three numbers representing the
interface versions it has had:
(CURRENT, REVISION, AGE)
This is overkill for us because we don't have the ability to have
multiple library revisions installed. So I propose we use:
(CURRENT, AGE)

So, CURRENT is trivial - its the bzr version tuple :
(0, 17, 0, 'dev', 0)
or
(0, 17, 0, 'final', 0)

and AGE needs to be something like:
(0, 0, 0) for incompatible - I'm assuming we never break ABI in a serial
number only change.
or
(0, 1, 0) for compatible on minor release back.

CURRENT and AGE are incremented every time we change an interface (and
make a release - flux within bzr.dev only results in one increment for
sanity).
AGE is reset to (0, 0, 0) if we break the ABI that is being tracked.
AGE is decremented appropriately if we drop deprecated methods. E.g. as
a worked example in 0.15 we dropped 0.8 compatibility. Lets pretend we
hadn't already broken our ABI and we had full 0.8 compatibility in 0.14
then it would have had
(0, 14, 0, 'final', 0), (0, 6, 0)
as its CURRENT, AGE tuple. So 0.15 would get (0, 7, 0) as its AGE tuple
- but because we dropped 0.8 compatibility we would reduce AGE to (0, 6,
0) - indicating we still had 0.9 compatibility but not 0.8.

So as a plugin author I can now write:
# require the 0.17 bzrlib ABI
bzrlib.abi.require_abi((bzrlib, (0, 17, 0)))
# require the 0.0.1 bzr-dbus ABI
bzrlib.abi.require_abi((bzrlib.plugins.dbus, (0, 0,  1)))

This would do the following:
 * When bzrlib breaks abi with 0.17, raise an error.
 * bzr bzr-dbus breaks abi, raise an error.

I think that errors are much more appropriate than this 'it might be
broken' warning business.

Sub-interfaces
--------------

I mention tracking multiple interfaces above. I think it would be quite
easy to have a small set of interfaces we track separately. This would
allow plugins that are not affected by e.g. Repository ABI changes to
not become incompatible when the repository ABI changes.

This is worth doing because having the ability to signal to plugins
whether they are going to be affected or not will make plugins more
robust: its likely we will break abi compatibility from time to time in
any one area, but release to release across the whole library.

One way of doing this is by having a number of names like "Tree",
"Branch", "Repository", "Transport", "Command" and "Other" to represent
these interfaces.

Another way is just to say that 'If a bzrlib module has an attribute
abi_age then there is a specific version compatibility for that module,
and if it does not then asking for compatibility with that module will
be check against bzrlib's overall compatibility (or against an 'other'
age string)'

I think I prefer using modules rather than a separate list; if we change
something like Inventory, that breaks Tree because its a leaky
abstraction, so users declaring an interface dependency on
bzrlib.workingtree will be safely notified. On the other hand using a
separate list of names makes it somewhat easier to document what folk
should depend on.

-Rob
-- 
GPG key available at: <http://www.robertcollins.net/keys.txt>.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20070613/0586da16/attachment.pgp