api stability

[Robert Collins]

On Mon, 2005-12-19 at 20:28 -0600, John Arbash Meinel wrote:

Ok, so the proposal is that:
(To be in place by the end of february (but start earlier where it makes
sense :)):


Symbols
-------
All symbols in bzrlib will be classified accordingly:


Private symbols: May change semantic or name at any point. Use of them
is discouraged but permitted - however such code will be prone to break
during upgrades.

Public symbols: The official API, usage is encouraged, and bug reports
about accidental breakage will result in us reinstating the public
symbol if at all possible. Public symbols will be preserved for *at
least* 6 months from the date it appears in a release of bzr, and at
least 6 months from the time it becomes deprecated/obsoleted. 

Deprecated public symbol: A public symbol that is deprecated - it will
be removed sometime with the next 6 months - check the docstring for it
for the exact date of planned removal. Where possible such use of such
symbols will issue a DeprecationWarning.


'symbol' : Is a public symbol.
'_symbol' : Is a private symbol to whatever context it appears in. If
that context is publicly extensible then its public [for extensions
only].
Specifically, _foo symbols in module scope are private.
              _foo symbols in class scope where the class
                   is named like 'Foo' are public for child classes.
              _foo symbols in class scope where the class is named 
                   like '_Foo' are private because the class is 
                   private and extension is not publically supported.

'__symbol' : Is a private symbol in all circumstances.

Exceptions
----------
Any exception that is raised by a public symbol in bzrlib and is a plain
python exception is a private symbol. 

All other exceptions are classified as per the symbol classification
guidelines above.

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/20051220/e73410a6/attachment.pgp