db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Db-derby Wiki] Update of "ForwardCompatibility" by DavidVanCouvering
Date Fri, 31 Mar 2006 19:33:18 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Db-derby Wiki" for change notification.

The following page has been changed by DavidVanCouvering:
http://wiki.apache.org/db-derby/ForwardCompatibility

------------------------------------------------------------------------------
  
  == Goal ==
  
+ This is our goal: An application which runs against a Derby release today ''that does not
depend on interfaces explicitly declared as unstable or on interfaces which are not documented''
will also run tomorrow against all subsequent patch and minor releases. We strive to minimize
churn for applications migrating to the next major release of Derby.  However these migrations
may entail application changes.
- Derby strives to acheive that public interfaces must remain forward compatible across releases
- The goal is to allow any application written against the public interfaces an older version
of Derby can run, without
- any changes, against a newer version of Derby.
  
  Detailed information on [http://db.apache.org/derby/papers/versionupgrade.html Derby's versioning
scheme]. 
  
  == Exceptions ==
  
  There will be occasions where the Derby community does introduce
+ regressions or what might be considered regressions by some. Examples of such exceptions
include fixing incorrect implementations of a standard or a correctness bug (for example a
query returning the wrong results).  Such changes may break existing applications.  We will
strive to avoid such changes but they may occur.  Any such change should be a deliberate choice
by the community, not by accident. 
- regressions or what might be considered regressions by some. Any such
- item should be a deliberate choice by the community, not by accident. 
  
- Examples are:
+ Specific examples:
  
       * Disabling !ResultSet.getXXXStream to be called twice on the same column in the same
row in 10.2. Previously 10.1 and 10.1 allowed this but returned the incorrect data. It seems
a reasonable choice as it stops incorrect behaviour and is in-line with the JDBC spec.
  
@@ -59, +56 @@

  
  This is an interface which we expect others to depend upon to remain stable enough for them
to build their own products or systems on top of.  Most of our public interfaces should be
given the stability level of Stable.  Stable interfaces should never change between minor
releases, and even between major releases changes should be extremely rare.  
  
+ '''It is important to note that having a major release does not mean that the release ''will''
have incompatible changes to a Stable interface.  It is just that a major release is the only
time where an incompatibility ''can'' be introduced on a Stable interface'''
+ 
  Any changes to Stable interfaces should be documented in the release notes.
  
  === Standard ===
@@ -120, +119 @@

        * Changing any documented side effects of the stored procedure
  
     * Compatible:
+       * Adding new allowable values to the input parameters
+       * Adding new allowable values to the return code
        * Adding columns to the result set
+       * Adding new allowable values to the existing columns of the result set
  
  In general, if you need to make a change for new functionality that is incompatible, it
is recommended that you create a new stored procedure and have the newer version of the code
use that new stored procedure.  
  
@@ -135, +137 @@

        * Changing the semantics of the table - what it represents
  
     * Compatible:
+       * Adding new allowable values to an existing column
        * Adding new columns to the table
        * Adding new indexes to the table
        * Changing the primary key for the table (?)
@@ -169, +172 @@

     * '''Stdout''': Changing format of stdout is an incompatible change.  Usually this is
not a Stable interface.
     * '''Environment variables''': can not remove use of or change interpretation of existing
environment variables.  Can add support for new environment variables.
     * '''Error messages''': can not change text of existing error messages.  Can add new
error messages.
+ 
+ === Changes to a Network Protocol ===
+ DRDA is the current protocol we use, and is the underpinning of client/server compatibility
+ 
+ Generally the network protocol needs to be versioned and the client and server need to negotiate
to a given version level.  The types of changes described below are changes to an existing
version of the protocol.  In general it is very difficult to make a compatible change to an
existing version of the protocol.
  
  === Other Miscellaneous Interfaces ===
  
@@ -199, +207 @@

  ||On-disk database file format||Private Stable|| || ||
  ||On-disk log file format||Private?|| ||Not sure if this is correct -- can this change incompatibly
across point or minor releases?||
  ||Metadata stored procedures||Private Stable|| ||These may be used by earlier clients to
implement JDBC !DatabaseMetadata calls||
- ||SQL States returned by Derby SQLExceptions||Stable?|| ||There is some debate that these
should be Unstable and that it should be OK to change them across minor releases if a bug
is found.  The argument is that very few developers actually depend on these, and that the
JDBC4 {{{SQLException}}} subclasses are more what people are going to rely upon.  Of course,
in Derby, if you change the underlying SQL State, you may very well end up getting a different
{{{SQLException}}} subclass... [My vote is to make these stable - DVC]||
+ ||SQL States defined by SQL specification||Standard|| ||There may be reasons to change a
SQL State at a minor release boundary; for example,if the wrong SQL State is being used. 
These will be addressed on a case-by-case by the community.||
+ ||Non-standard Derby SQL States||Unstable|| || ||
  ||Error message text||Private|| ||Note that this means canon-based tests can not make claims
that a regression has occurred because the output from error messages has changed||
  ||Install directory hierarchy||Unstable|| || ||
  ||Tools (ij, dblook, etc.) command-line name and arguments||Stable|| || ||
@@ -238, +247 @@

  
  === Would this set of rules drive the decision of when to declare a major release versus
a minor release? ===
  
- They would be one of the deciding factors, likely a major deciding factor.  Other factors
will likely be involved.
+ They would be one of the deciding factors, likely a major deciding factor.  Other factors
will likely be involved.  It is more than likely that we may want to declare a new major release
even though we have not introduced any incompatibilities.
  
  === We currently don't have any rules about when we would change to 11.0 from the current
10.x pattern. ===
  
- Making an incompatible change to a Stable or Standard interface would require us to change
to 11.0
+ Making an incompatible change to a Stable or Standard interface would require us to change
to 11.0.
  
  === Would it be because someone changed some "Standard" interface in an incompatible way
that we move to 11.0? ===
  

Mime
View raw message