bzr 2.1 retrospective

[Martin Pool]

On 20 February 2010 17:37, Robert Collins <robert.collins at canonical.com> wrote:
> On Sat, 2010-02-20 at 01:32 -0500, Aaron Bentley wrote:
>
>> Martin Pool wrote:
>> > One nice outcome of stable branches is that people can remove old
>> APIs
>> > more easily, and plugins within a series will not be broken.  It's
>> > very good to see for example Jelmer recently deleting unnecessary
>> > APIs.
>> >
>> > * affirmed: API stability by code branch
>> > * affirmed: delete crufty code!
>>
>> These are great things, but as the maintainer of bzr-pipeline, it's
>> felt
>> like a bumpy ride following the betas.  APIs have been more subject to
>> change in the beta series, yet because they're betas, require_any_api
>> doesn't distinguish between beta1 and the final released version.  I
>> think there's room for improvement here.
>
> I agree. I'd actually like to see API deprecation be done for any change
> that is a break vs the last stable release. That way, *if* I don't want
> to update, I can ignore things until the trunk goes stable again.

> As it is, it appears to be that trunk is neither doing API stability vs
> last-stable, nor deprecations within-trunk, which makes running a plugin
> in trunk annoying.

This is a useful thing to bring out of the retrospective, and I think
we can do better here, also better than just going back to where we
before.

It seems to me the domain is:

Some code constructs are hard to deprecate cleanly: for instance
methods that may be either called or overridden by plugins, or
variables rather than functions.  It's true that given sufficient
creativity you can get around this in many cases.  However,
historically it seems to cause people either to put more time and
effort (and more risk of bugs) into formulating the deprecation than
into the original change, or they simply dismiss it as too hard and
the thing never gets cleaned up.  I do want to improve this because it
makes a big difference to the ease with which we can improve bzr and
with which people can contribute.

Of course although some things are hard to deprecate, others are not,
and we might as well keep deprecating them.

Separating public vs private methods for stability guarantees was not
successful, for reasons discussed previously.  It may still be
worthwhile for documentation.  Essentially any api we publish might be
depended upon by clients.

Deprecation warnings are a bit annoying and pointless to show to
users, who are generally unlikely to get in and update the plugin
code.  We want developers to see them and for users they should
ideally have it either just work, or be told they need to update.

Many users now get bzr and the plugins as a set, with consistency
ensured by some intermediate party such as the windows or mac package
builder, or the distro packager.

So one thing we could do is just say "please deprecate things that
were in the previous release rather than just removing them, if
possible."  But perhaps someone has a better idea.

-- 
Martin <http://launchpad.net/~mbp/>