db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Levitt <de...@mylevita.com>
Subject Re: Should we vote on it? (was Re: Discussion (in preparation for a vote) on interface stability table)
Date Sat, 01 Apr 2006 03:01:28 GMT
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"
<David.Vancouvering@Sun.COM> 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"
> > <David.Vancouvering@Sun.COM> 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
> >>>
> >>>
> >>
> > 
> 


Mime
View raw message