[qbzr] Re: API requests from a qbzr dev

Stephen J. Turnbull stephen at xemacs.org
Fri Oct 9 01:33:57 BST 2009

Martin Pool writes:

 > 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.

Why do you think that?  Just because various folks have complained
about either the policy or the results?  This is a very hard problem.
Before you drop the policy, I think you should think carefully about
(1) what you hoped to accomplish (and now are saying has not been
successully accomplished), and (2) what you realistically could have
expected to accomplish.

 > Firstly, it's proved quite hard to keep good api compatibility while
 > changing underneath, on any api.

"If it hurts, that's good: it means you're not dead yet!" :-)

 > But third and most importantly, in practice plugin developers don't
 > restrict themselves to public APIs.

Sure.  Consenting adults.

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

I think that's a bad idea.  You may make mistakes, but you can't let
the individual plugins drive your decisions.  It needs to be the other
way around.  If you think an API needs to be allowed to evolve or
should be exposed to clients only if wrapped, make it private and any
client that uses it should consider themselves warned.  If an API is
public, OTOH, the developers of the client have a right to get upset
if it 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.

This begs the question of "more appropriate", though.  And it's not a
question of "allowed" in Python.  It's what do you support.  I don't
really see why you can't leave an API private, have a plugin developer
find a use for it, and he develops his product simultaneously
negotiating with you for a public interface.  Maybe it stays private,
and he shoulders the whole risk; maybe you make it public, and suffer
the inflexiblity; maybe you compromise on a new interface, giving him
what he needs but reserving other aspects of the original interface
and behavior.

More information about the bazaar mailing list