Mailing-List: contact derby-dev-help@db.apache.org; run by ezmlm
Precedence: bulk
Reply-To: <derby-dev@db.apache.org>
Received-SPF: pass (asf.osuosl.org: local policy)
Date: Thu, 30 Mar 2006 15:08:01 -0800
From: "David W. Van Couvering" <David.Vancouvering@Sun.COM>
Subject: Re: Should we vote on it? (was Re: Discussion (in preparation for a
 vote) on interface stability table)
In-reply-to: <442C5DFA.1030907@sbcglobal.net>
To: derby-dev@db.apache.org
Message-id: <442C64D1.8000408@sun.com>
MIME-version: 1.0
Content-type: text/plain; charset=ISO-8859-1; format=flowed
Content-transfer-encoding: 7BIT
User-Agent: Mozilla Thunderbird 1.0.7 (Windows/20050923)
References: <4429C948.1050606@sun.com> <442C4E76.1090504@sun.com>
 <442C4F44.90409@sun.com> <442C5DFA.1030907@sbcglobal.net>

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