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