Brainstorm, What constitutes a public API? (was Re: [Zope3-dev] Re: APIs breakage)

[Jim Fulton]

Jim Fulton wrote:
> Casey Duncan wrote:
> 
...

>> In a general sense in Zope 3, what does it mean for an API to be
>> private? Who should or shouldn't use it? The current module, package,
>> the framework, zope.app?
> 
> 
> I think we need to decide this.

OK, let's brainstorm.

I suggest:

- There be public interfaces and private interfaces.

   Here, bublic or private doesn;t say anything about
   security, but about the stability of and long-term
   commitment to an API.

- Public interfaces should be stable and hard to change.
   They *can* be changed, but only through a gradual change process
   involving deprecation warnings and a long period of backward
   compatability.

- Package 'interfaces' modules should *only* contain public
   interfaces. This means that, when developing new sofware,
   you should avoid ceating interfaces modules until you are willing
   to carve an interface in stone.

Thoughts?

Jim

-- 
Jim Fulton           mailto:jim at zope.com       Python Powered!
CTO                  (540) 361-1714            http://www.python.org
Zope Corporation     http://www.zope.com       http://www.zope.org