Re: Should we vote on it? (was Re: Discussion (in preparation for a vote) on interface stability table)

[David W. Van Couvering]

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