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 Thu, 30 Mar 2006 23:40:46 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

------------------------------------------------------------------------------
     * Jar file names
     * Class names
  
- == What is an Incompatible Change? ==
- 
- What constitutes an incompatible change depends upon the type of interface
- 
- '''TODO - Provide definition for "incompatible change"'''
- 
  == Stability Levels ==
  
  To help describe the types of stability guarantees Derby provides for a given interface,
we identify the following stability levels.  These definitions are inspired by the [http://www.opensolaris.org/os/community/arc/policies/interface-taxonomy/
OpenSolaris interface taxonomy]
@@ -104, +98 @@

  Interfaces that have been reclassified to Deprecated should be documented in the release
notes.
  
  A deprecated interface may be removed from the project after four minor and/or major releases.
+ 
+ == What is an Incompatible Change? ==
+ 
+ What constitutes an incompatible change depends upon the type of interface
+ 
+ === Changes to Java Classes ===
+ 
+ We are going to follow the definitions for what types of changes are considered acceptable
for what types of releases as defined by the Apache Jakarta Commons project.  See
+ 
+ http://jakarta.apache.org/commons/releases/versioning.html
+ 
+ === Changes to Stored Procedures ===
+ 
+ System procedures and metadata procedures are both Stable interfaces, so it is important
to understand what entails a compatible change for stored procedures.
+ 
+    * Incompatible:
+       * Changing the name of the stored procedure
+       * Changing the signature (input params, output params, and return value)
+       * Changing the name, type or order of existing columns in the result set
+       * Changing any documented side effects of the stored procedure
+ 
+    * Compatible:
+       * Adding columns to 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.  
+ 
+ 
+ === Changes to Database Tables ===
+ 
+ Documented system tables are a Stable interface, so care must be taken when considering
changing these
+ 
+    * Incompatible:
+       * Changing the name of the table
+       * Changing the names, types, or order of existing columns in the table
+       * Changing the semantics of the table - what it represents
+ 
+    * Compatible:
+       * Adding new columns to the table
+       * Adding new indexes to the table
+       * Changing the primary key for the table (?)
+ 
+ === Incompatible Changes for Data File Formats ===
+ 
+ '''I need help with this one'''
+ 
+ === Changes to Configuration Properties ===
+ 
+    * Incompatible:
+       * Changing the name of the property
+       * Removing a property
+       * Changing the default value of a property
+       * Changing the valid values for a property
+       * Changing the meaning of a property
+ 
+    * Compatible
+       * Adding a new property
+       * Adding support for new valid values for a property
+ 
+ === Changes to Command Line Interfaces (CLI) ===
+ 
+ These are both scripts and Java classes that implement a command-line interface
+ 
+ A CLI is subdvided into multiple interfaces: its name, its arguments, its return code, stdin,
stdout, environment variables it uses, its error messages.  Each of these may have a different
stability level.  I describe an incompatible change for each of these
+ 
+    * '''Name''': Cannot change the name of the CLI (script name or class name)
+    * '''Arguments''': Cannot change names, valid values or semantics of existing arguments.
 Cannot remove arguments. Can add new arguments.
+    * '''Return code''': Cannot change semantics of or remove existing return codes.  Can
add new return codes.
+    * '''Stdin''': Changing format or expected values from stdin is an incompatible change
+    * '''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.
+ 
+ === Other Miscellaneous Interfaces ===
+ 
+ Here we describe what an incompatible change means for other miscellaneous interfaces
+ 
+    * '''Port Number''' : Cannot change the default port number
+    * '''Network protocol''' : Cannot remove existing messages, change the signature or semantics
of a message, or the format of a reply to a message.  Can add new messages.
+    * '''Miscellaneous file or string formats''' : Cannot change the semantics or format
in any way and remain compatible.  Normally this is handled by versioning the format.
  
  == Interface Table ==
  
@@ -125, +198 @@

  ||derby.log file format||Unstable|| ||
  ||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?||
- ||Precompiled metadata stored procedures||Private Stable|| ||These may be used by earlier
clients to implement JDBC !DatabaseMetadata calls||
+ ||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]||
  ||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|| || ||

Mime
View raw message