plugin api versioning (Re: [ANN] bzr 2.4b1 has gone gold)

[Martin Pool]

On 25 March 2011 12:03, Aaron Bentley <aaron at aaronbentley.com> wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> On 11-03-19 12:13 PM, Gordon Tyler wrote:
>> Using the same versions as bzr 2.3, bzr-pipeline and bzr-svn are failing
>> to load with bzr 2.4b1.
>>
>> pipeline (failed to load)
>>   ** Unable to load plugin 'pipeline'. It requested API version (2, 3,
>> 0) of module <module 'bzrlib' from
>> '/Library/Python/2.6/site-packages/bzrlib/__init__.pyc'> but the minimum
>> exported version is (2, 4, 0), and the maximum is (2, 4, 0)
>
> I know it's too late, but I thought I'd try to fix this, only to realize
> that I don't know what I should be doing about versioning these days.
>
> With pipeline, I'm trying to play nice by using the official versioning
>  functions instead ofapi instead of the homebrew approach used in
> bzrtools.  The idea was supposed to be that bzr wouldn't update its
> minimum API version very often, and so plugins could declare
> compatibility with certain API versions and wouldn't have to update
> until compatibility was actually broken.   But these days, we seem to
> update the API version in sync with the bzr version, so declaring
> compatibility with bzrlib 2.3 doesn't do any good for pipeline when
> 2.4b1 comes out.
>
> But I don't want to declare that a release is compatible with bzrlib 2.4
> until I've tested it with a final version of that API, i.e. bzr 2.4.0.
> So I really shouldn't release bzr-pipeline 1.2 until bzr 2.4.0 goes gold.
>
> In this situation, it seems like the homegrown versioning in bzrtools
> works better, because it tolerates betas of the next release.
>
> So maybe I should be releasing betas of pipeline?  Seems a bit crazy
> when I've hardly changed anything.

I think that the API versioning model is not a good fit for reality.
(It's been discussed before on the list so I won't rehash the reasons
but basically anything but incrementing on every release is too loose;
breaking all plugins on every release is too tight; and fine-grained
versioning per class is too hard.)  On the whole I think
distinguishing "api version" from "library version" in Python is
complexity without much benefit.

What I think we should move to is to have declarations of

  plugin $name $version_range works* with bzr $version
  plugin $name $version_range does not work with bzr $version

which is a lot like what's done in Debian packages.

It should be possible to insert these on either side so if we know bzr
2.4.2 breaks bzr-foo 3.141 then we can say so in bzr rather than
forcing a new bzr-foo release.

I would suggest then that plugins could normally just say ">= bzr 2.3"
and assume they will probably work on later versions.  If it turns out
they don't we can either update the plugin to say they're broken or
update bzr to say so.

* well, "is believed to work" ;-)

Martin