api stability

[John Arbash Meinel]

Robert Collins wrote:
> 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 :)):
> 

+1 from me.

John
=:->

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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 256 bytes
Desc: OpenPGP digital signature
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20051219/375acc1e/attachment.pgp