db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "David W. Van Couvering" <David.Vancouver...@Sun.COM>
Subject Re: Should we vote on it? (was Re: Discussion (in preparation for a vote) on interface stability table)
Date Fri, 31 Mar 2006 19:35:13 GMT
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