[qbzr] Re: API requests from a qbzr dev

[Martin Pool]

2009/9/26 Vincent Ladeuil <v.ladeuil+lp at free.fr>:
> Now, we've got meat to talk about stability... just to be clear:
> we *don't* guarantee that if *any* of the above change we will:
> 1) document it, 2) deprecate it properly (i.e. with warnings).
>
> I think the above is enough to *start* the discussion and see
> what should be made public, from there we can file bugs.

[old postponed draft, but still worth sending i think.]

I've said this before, but perhaps not here, and perhaps not updated
the documentation.

Our approach used to be: there is a public api, which will be stable,
and a private api which will be unstable.  This was worth a try but I
think has not been successful in practice, so we should try something
else.

Firstly, it's proved quite hard to keep good api compatibility while
changing underneath, on any api.  This is partly that we've been
trying to make structural changes to improve things, which involves
changing not just what's behind an interface but the concept of the
interface.  (See various posts from Robert.)  It's partly that in
Python it's fairly hard to define just what behaviour is part of the
interface and what's not: it's more than just "there's a function you
can call" but you can also monkeypatch it, you can subclass the
implementation, you can depend on varargs handling working a
particular way...  Python just intentionally is not a language that
tends to make strong distinctions between interface and
implementation, which is not to say it's all Python's fault.

Secondly, we haven't had a really good way to communicate to plugin
developers when they need to update.  We have api levels and
deprecation warnings, but they tend to end up with end users seeing
warnings they shouldn't see.  We can do more as far as hiding more
warnings from users.  (By 'plugin developers' I include all API client
developers.)  And they don't totally cover interfaces other than
calling our methods - we can't directly deprecate subclassing, or
relying on an exception.

But third and most importantly, in practice plugin developers don't
restrict themselves to public APIs.  It's not that they're bad
developers - on the contrary, it would just really not be feasible for
them to do it.  If for example Gary needed PreviewTree functionality,
the theoretical answer is that he should send a mail asking for it to
be public, then after some discussion we might agree and rename the
interface to be public.  But in practice this means a substantial
delay before we make a release that has it public, and code that does
rely on it being public won't work with previous releases, even if
they have the exact same code there.  This is clearly suboptimal.  And
that's leaving aside the temptation for us to say "no, it's not
public, we need to do X first.)  So this would introduce a month-plus
handoff into Gary's work, when the code he needs is actually there
already.

So in sum, what I think we should do from here is:

Not make a sharp distinction between public/stable and non-stable
interfaces.  Whatever API clients depend on is what they depend upon.

Keep a stable API by keeping stable code in stable branches, not by
trying to preserve APIs while the code changes.

Use underscores only to indicate 'relatively private' - something that
normal users of the class shouldn't look at, not because they're not
allowed to, but because there's probably a more appropriate interface.

Get a good feedback cycle where plugin developers ask for clean APIs
to do what they want,  and they get at least good advice on how to add
it and prompt reviews.  This is starting.

Use deprecation warnings mostly during beta cycles to help plugins
update themselves, so that when we arrive at a stable rc we also have
plugins up to date, or pretty close to up to date.

Think better about how to communicate deprecation warnings and
out-of-date-ness to both plugin authors and users.

Get the plugins included in the PPA and Babune and test them as we go along.

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