Re: [proposal] frozen/non-frozen interfaces

[Richard Feit]

Based on Daryl's and Kyle's comments, I think we can simply go with 
@UnderConstruction in the case where we have an interface that the user 
may implement, but it's not yet ready for prime time (i.e., we're not 
ready to freeze it).  Any interface not marked as @UnderConstruction 
would be by default immutable.  I actually don't think we need a 
versioning scheme here, since once an interface goes public 
(@UnderConstruction is removed), it can't change.

It's possible that when a major release is cut, we'll prohibit leaving 
any interfaces marked @UnderConstruction.

Does that make sense?  We may want a different annotation for interfaces 
that we don't expect the user to implement (@InternalImplementation?), 
but that seems like a separable issue.

Rich
Mark Griffith wrote:
Great, lets add the frozen and underconstruction and it seems were done.
cheers
mbg 

 

-----Original Message-----
From: Kyle Marvin 
Sent: Monday, October 11, 2004 9:37 PM
To: Beehive Developers
Subject: RE: [proposal] frozen/non-frozen interfaces

There is an existing proposal for a release process out on 
the Beehive Wiki, that includes the following statements:

"After the first GA quality version 1.x.z is cut and 
offically released, Beehive will make best effort to maintain 
backwards compatibility at all times. Beehive will have a 
strict policy of maintaining backwards compatibility within a 
major version. 

- Beehive can deprecate APIs. If an API must be deprecated, 
it will be documented as deprecated in one major release and 
removed in the following major release. 
- If Beehive must break backwards compatibility, Beehive will 
provide migration utilities where possible."

http://wiki.apache.org/beehive/Release_20Process
-- Kyle
   

-----Original Message-----
From: Mark Griffith
Sent: Monday, October 11, 2004 8:53 PM
To: Beehive Developers
Subject: RE: [proposal] frozen/non-frozen interfaces
Some additional comments.
a) freezing should include a notion of versioning, similar to what 
javadoc does using @since, this allows you to build in from the 
beginning a notion of versioning to deal with later changes 
     

to frozen 
   

code.  Cause it will happen. ;)
b) we need to establish a policy for beehive regarding under 
construction, freezing policy, compatibility between releases
(major/minor) of frozen public methods as well as a deprecation 
policy.

BEA has policies for this already, however Beehive needs to 
     

establish 
   

this as well for itself, even if they are initially aligned 
     

with what 
   

BEA has decided, they should be published as part of Beehive.
Who would you like to be on point to deliver this?
Cheers
mbg
     

-----Original Message-----
From: Kyle Marvin
Sent: Monday, October 11, 2004 9:19 AM
To: Beehive Developers
Subject: RE: [proposal] frozen/non-frozen interfaces
For externally exposed ("public") interfaces, it is worth noting 
that there are actually two sub-types:

1. Ones where an end user is expected to provide implementation 
classes of 2. Ones where user code might write code against the 
interface, but doesn't provide the implementation

The Controls runtime has lots of examples of #2... in fact, all 
public APIs are separated out in the
org.apache.beehive.controls.api package space.   Often, there 
are corresponding implementations in 
org.apache.beehive.controls.runtime that are the 
       

(private) runtime 
   

implementation of the public APIs.
For type #1 above, freezing interfaces is important to avoid 
breaking user code.  If you add a method, then suddenly all 
user-authored implementations become broken.

For type #2 above, a more relaxed constraint of ensuring that the 
interface remains syntactically and semantically compatible seems 
OK.  This is because the public APIs and supporting impls will 
always version and ship together as newer versions of the runtime 
are provided (both live in
controls.jar).   It is OK to add methods here, as long as the 
added methods don't in any way change the behavior of existing 
methods.

-- Kyle
       

-----Original Message-----
From: Richard Feit
Sent: Saturday, October 09, 2004 11:48 AM
To: Beehive Developers
Subject: Re: [proposal] frozen/non-frozen interfaces
That's probably the essence of what we need.  So would an
         

@frozen (or
       

@incomplete) annotation make sense across the project?
Daryl Olander wrote:
         

I agree that until a major release we should have freedom
           

to change
       

newly introduced APIs.  Perhaps we should mark these in some
           

way, such
         

as the unfrozen annotation.
On Sat, 09 Oct 2004 10:21:37 -0600, Richard Feit
           

<[EMAIL PROTECTED]> wrote:
         


           

Interesting.  In the ServerAdapter case, I can see
             

switching to a base
         

class rather than using an interface.  But if we do 
             

have other 
   

interfaces or classes that are marked public only for our
             

internal
       

cross-package use, we should simply have a clear standard for 
identifying which ones are internal.

An unresolved issue, though, is public interfaces that
             

are "under
     

construction".  I'd argue that even if we do a point release, 
ServerAdapter isn't ready for public (user) use.  Brave
             

souls can try
         

it, but I'd like for there to be some way to mark an
             

interface as not
         

ready for public consumption.  Seem like a valid goal?
Rich

Daryl Olander wrote:
  

             

In general, I agree except for having unfrozen public
               

exposed interfaces..
         

I think what we really should do is have two classes 
               

of code, 
   

externally exposed and internal.
For all externally exposed classes, we must maintain the
public/protected signature of the class.   For example, 
               

in the Tag
       

set, there are a set of base classes and we should
               

maintain their
       

public/protected signature (not removing methods, and
               

maintaining
       

existing method signatures, maintaining semantics).  We
               

can add new
       

methods and overloads, and deprecate existing methods.   
               

We should
       

create a test suite that verifies this signature.
For externally exposed interfaces there may be no change
               

at all to
       

them.  If a change needs to be made we need to 
               

introduce a new 
   

interface (xxxxEx or xxxx2) which will produce the hell
               

MS has in
       

their APIs.
For internal  packages and classes, these will be clearly
               

marked and
         

we can change them from release to release.  Of course, if
               

we find a
         

wide spread use of an internal API, we may be force to not
               

change it
         

also.  This is basically community promotion of an
               

internal API to an
         

external API.
If we do support "unfrozen" APIs, we need to be very
               

careful and not
         

use this much because we are stating that something is
               

public, but may
         

change and break code.  I'm not sure If I really agree
               

with this.  I
         

think a better design pattern is to avoid Interfaces and
               

instead use
         

base classes because they may be changed.
On Fri, 08 Oct 2004 11:04:30 -0600, Richard Feit
               

<[EMAIL PROTECTED]> wrote:
         

    

               

OK, taking a cue from Mozilla's XPCOM... what do we think
                 

about making a
         

distinction between frozen and non-frozen interfaces?  
                 

Simply put,
       

frozen interfaces never change, while non-frozen
                 

interfaces can change.
         

I'd imagine that:
 a) new interfaces are non-frozen until a release
 b) all end-user interfaces (e.g.,
org.apache.beehive.controls.api.bean.Extensible) get
                 

frozen at a release
         

 c) internal/advanced interfaces (e.g.,
org.apache.beehive.netui.pageflow.ServerAdapter) don't
                 

necessarily get
         

frozen, so implementors may have to add or change methods
                 

when upgrading
         

to a new release.
If we did this, we could have a simple annotation to
                 

denote frozen
       

interfaces, like @frozen.
The alternative, of course, is to assume *all* interfaces
                 

are frozen at
         

a release: we can never change signatures, and if we ever
                 

want to add
         

something, we add a new interface (ServerAdapter2,
                 

ServerAdapter3, etc.)
         

in the Microsoft vein.
Thoughts?
Rich