P.S. David, I read my original reply and even I didn't understand it! I think my latest response is slightly more clear.... Sorry all, Jeff
--- "David W. Van Couvering" <[EMAIL PROTECTED]> wrote: > Hi, Jeff. I've been quiet on this comment because I > didn't fully > understand it. > > I *think* what you're saying is that an interface > can not be considered > Stable or Unstable unless it's actually documented. > Is that right? > > David > > Jeff Levitt wrote: > > From a documentation perspective, I think if we > are > > going to say on this page that items are stable AS > > DOCUMENTED in the user documentation, then we also > > need to put in some sort of requirement on this > page > > that says any changes made to the stability of an > item > > MUST be documented as well in order to be > committed an > > considered stable. Its not stable if its not > > documented and we are telling people that it is > stable > > as documented. Agreed? > > > > I think this is something that would be good to > put in > > to make sure that developers understand the > importance > > of documenting their work, whether its something > new > > or a change to something that exists, and that its > not > > just going to magically show up in the > documentation > > if they put it in the code (unless its javadoc) :) > > > > --- "David W. Van Couvering" > > <[EMAIL PROTECTED]> wrote: > > > > > >>Thanks for your comments, Kathey, and yes, it can > >>definitely wait a > >>week. It was just so quiet that I thought I'd do > a > >>"ping" and see if > >>there was more to come from everyone. > >> > >>Responses below... > >> > >>Kathey Marsden wrote: > >> > >>>I wish I had more time to look at this but I > >> > >>think that I would add > >> > >>>these things. > >>> - In general any documented behaviour is a > >> > >>stable interface, unless > >> > >>>specifically documented here or in the > >> > >>documentation as unstable. > >> > >>I'm not sure how to handle this. What does it > mean > >>to "incompatibly > >>change" documented behavior? > >> > >>Usually the behavior is in relation to a given > >>interface. So perhaps in > >>our definition of what it means to incompatibly > >>change an interface > >>means you can't change the documented behavior of > >>that interface (e.g. > >>the "contract" of that interface). > >> > >>I think it's also fair to say that unless > explicitly > >>called out in the > >>table as otherwise, one can assume a publicly > >>documented interface is > >>Stable. > >> > >> > >>>- Derby will at a minimum negotiate down to the > >> > >>lower interface > >> > >>>revision level: > >>> - When different versions of Derby client > >> > >>and server are used > >> > >>>together (in the same or different JVM's) > >>> - When different jvm versions are used on > >> > >>client and server. > >> > >>I think this is a solution that provides a > guarantee > >>of stability to the > >>client/server interfaces. I can add this as a > note, > >>however. > >> > >>I think by calling out the *specific* interfaces > >>that the client depends > >>upon (DRDA, metadata procedures, system stored > >>procedures, ???) and > >>marking them as Stable or Private Stable is a > Really > >>Good Idea in our > >>attempts to provide the guarantee of client/server > >>compatiblity. Note, > >>for example, some of us newbies changing the > >>metadata procedures willy > >>nilly because we were unaware of the impact on > >>compatibility. Having > >>these called out will make us all more conscious > of > >>what we can and > >>can't do within the system. > >> > >> > >>>In the interface table I would add: > >>>- Defaults returned by DatabaseMetaData methods > > >> > >> Stable > >> > >>>- Documented defaults > > >> > >> > >> > >>>Stable > >>>- console output format for tools and network > >> > >>server Unstable > >> > >>>- System stored procedures > > >> > >> Stable > >> > >>OK, I'll add these. I think the console output > >>format for tools and > >>server should actually be marked Private -- it's > not > >>documented in the > >>user documentation, and can change at any time. > >> > >>Dumb question: are system stored procedures in the > >>user documentation? > >>If not, perhaps they should be Private Stable > rather > >>than Stable? If > >>they're not documented, what is driving the > >>requirement that they be > >>stable - client/server compatibility? > >> > >> > >>>Under notes It would be good to mention: > >>> > >>> . > >>> > >> > >>OK > >> > >> > >> > >>>Could we wait a week for a vote? I think I > need > >> > >>to study this some more. > >> > >>>Thanks David for doing this. > >>> > >> > >>Yes, sure, and you're welcome. > >> > >>David > >> > >> > >>>Kathey > >>> > >>> > >> > > >
