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