api stability rules

[Martin Pool]

This follows on from the conversation in December and recently about how
to mark bzrlib interfaces that are promised to be stable in the future,
so as not to break external code.  We're agreed that in general
functions/classes with _-prefixed names should be treated as
bzrlib-internal and avoided by external clients.

I talked to Robert a bit more.  The only area of disagreement is how to
mark members of a class which shouldn't be relied upon by bzrlib
clients, but can be used by bzrlib client code that is subclassing the
class.  In other words, how to represent the equivalent of protected
access in C++ or Java.  

What I propose is:

 * we try to give __names to make things genuinely private when they can
be

 * give internal or non-stable interfaces _names

 * we defer a decision about whether or how to specially treat members
that can safely be accessed by external subclasses but not otherwise;
that is for the moment give them underscores or not just based on
whether they're stable interfaces, regardless of their use in
subclassing.

-- 
Martin

-------------- 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/20060106/eaa9c066/attachment.pgp