api stability

[Robert Collins]

Hi,
	Martin and I have had a request from the folk writing the
launchpad/supermirror/hct functionality within Canonical - that builds
on top of bzr - to provide some sort of 'stable' api from the end of
February. We had a phone chat about what this might mean, and I thought
I'd see what you guys (who would be being asked to provide this in
patches) thought.


The basic idea is that 'public' symbols would be preserved for ~ 6
months, and that would use standard refactoring techniques to leave
compatability apis in place as we restructure. Obviously the more
changes we have done before we start this the easier it is. So if we can
get something-like checkouts, repositories and
nested-trees-in-inventories done before then, we should have most of the
moving parts in place.

So the heuristic Martin and I think would work well is:

Modules, methods, functions and classes beginning with _ are private:
folk can use them, but no warranty is made for longevity of those
calls : folk that want them preserved need to ask us to make them
public.
Exceptions that are raised that are Bzr prefixed are public and will
likewise be preserved, but native exceptions like KeyError etc are
subject to change without notice. 

The idea here is that its easy for us when we change the code to know if
we need to leave a forwarding stub behind: 
 * If its a non _ prefixed thing we leave a stub behind with a datestamp
for removal.
 * If its a Bzr exception type the same thing applies.

Theres a little infrastructure we can write that can assist us - giving
us exceptions that pun as the old type and also match the new type, so
we are not hindered in any substantial way as we write new code.


What do you think: Is this something the code base might be ready for by
the end of february? Is it a good thing (offering a stable api for
developers)? Does the above approach approach make technical and social
sense?

Rob

-- 
GPG key available at: <http://www.robertcollins.net/keys.txt>.
-------------- 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/20051215/0259915c/attachment.pgp