Derby interface stabilities

["David W. Van Couvering" <Da...@Sun.COM>]

The discussion of the stability of SQL States inspired me to finally 
apply what I've learened here at Sun in terms of explicitly declaring 
the stability one guarantees for each interface and applying it to Derby.

I have updated Dan's forward compatibility page with a draft of what 
this might look like.  Dan, I took all the interfaces you called out and 
merged them into the interface table, and added many more, as well as 
some background information around interfaces and stability definitions.

I think one component that is still missing is: what does it mean to 
make an incompatible change, for various types of interfaces?  As an 
example, it's OK to add a column to an existing system table, but not OK 
to change the type of an existing column; it's OK to add columns to the 
result set of a metadata query; it's OK to add a method to an existing 
interface but you can't change an existing method, and so on.

Please see http://wiki.apache.org/db-derby/ForwardCompatibility, and 
modify or comment as you see fit.  It is not necessarily my itch to be 
the one responsible for maintaining this interface table; I hope that's 
something that can be shared across a number of us. But I did want to 
get something out there for us to look at and start discussing.


David

Re: Derby interface stabilities

[Oystein Grovlen - Sun Norway <Oy...@Sun.COM>]

David W. Van Couvering wrote:

> Please see http://wiki.apache.org/db-derby/ForwardCompatibility, and 
> modify or comment as you see fit.  It is not necessarily my itch to be 
> the one responsible for maintaining this interface table; I hope that's 
> something that can be shared across a number of us. But I did want to 
> get something out there for us to look at and start discussing.

Nice work.

I think we should also mention file formats for database and log files. 
  I guess those are unstable since we allow them to change between minor 
releases.  (Otherwise soft upgrade would only be an issue for major 
releases.)

-- 
Øystein

Re: Derby interface stabilities

["David W. Van Couvering" <Da...@Sun.COM>]

OK, fixed.

David

Rick Hillegas wrote:
> Hi David,
> 
> This is great. Thanks for pulling this together. I have one nit: 
> Currently, we say that the Release Notes document only changes to 
> Unstable interfaces. I think the Release Notes should document changes 
> to Stable and Standard interfaces (which ought to be rare), and the 
> Release Notes should document the transition of  interfaces from 
> Supported to Deprecated to Removed.
> 
> Regards,
> -Rick
> 
> David W. Van Couvering wrote:
> 
>> The discussion of the stability of SQL States inspired me to finally 
>> apply what I've learened here at Sun in terms of explicitly declaring 
>> the stability one guarantees for each interface and applying it to Derby.
>>
>> I have updated Dan's forward compatibility page with a draft of what 
>> this might look like.  Dan, I took all the interfaces you called out 
>> and merged them into the interface table, and added many more, as well 
>> as some background information around interfaces and stability 
>> definitions.
>>
>> I think one component that is still missing is: what does it mean to 
>> make an incompatible change, for various types of interfaces?  As an 
>> example, it's OK to add a column to an existing system table, but not 
>> OK to change the type of an existing column; it's OK to add columns to 
>> the result set of a metadata query; it's OK to add a method to an 
>> existing interface but you can't change an existing method, and so on.
>>
>> Please see http://wiki.apache.org/db-derby/ForwardCompatibility, and 
>> modify or comment as you see fit.  It is not necessarily my itch to be 
>> the one responsible for maintaining this interface table; I hope 
>> that's something that can be shared across a number of us. But I did 
>> want to get something out there for us to look at and start discussing.
>>
>>
>> David
> 
> 
> 

Re: Derby interface stabilities

[Rick Hillegas <Ri...@Sun.COM>]

Hi David,

This is great. Thanks for pulling this together. I have one nit: 
Currently, we say that the Release Notes document only changes to 
Unstable interfaces. I think the Release Notes should document changes 
to Stable and Standard interfaces (which ought to be rare), and the 
Release Notes should document the transition of  interfaces from 
Supported to Deprecated to Removed.

Regards,
-Rick

David W. Van Couvering wrote:

> The discussion of the stability of SQL States inspired me to finally 
> apply what I've learened here at Sun in terms of explicitly declaring 
> the stability one guarantees for each interface and applying it to Derby.
>
> I have updated Dan's forward compatibility page with a draft of what 
> this might look like.  Dan, I took all the interfaces you called out 
> and merged them into the interface table, and added many more, as well 
> as some background information around interfaces and stability 
> definitions.
>
> I think one component that is still missing is: what does it mean to 
> make an incompatible change, for various types of interfaces?  As an 
> example, it's OK to add a column to an existing system table, but not 
> OK to change the type of an existing column; it's OK to add columns to 
> the result set of a metadata query; it's OK to add a method to an 
> existing interface but you can't change an existing method, and so on.
>
> Please see http://wiki.apache.org/db-derby/ForwardCompatibility, and 
> modify or comment as you see fit.  It is not necessarily my itch to be 
> the one responsible for maintaining this interface table; I hope 
> that's something that can be shared across a number of us. But I did 
> want to get something out there for us to look at and start discussing.
>
>
> David