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 Wed, 29 Mar 2006 19:12:04 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:

  Initial set of public interfaces from an e-mail discussion on
  the derby-dev list. The list is subject to change.
+ [[TableOfContents]]
  == Goal ==
@@ -78, +80 @@

  Private interfaces are interfaces which are not documented for external users, and generally
users should not be depending upon,
  and which can change at any time. 
- Some private interfaces must have a level of stability beyond the private guarantee, even
though they are not documented.  For example, the on-disk format for Derby databases must
remain stable across minor releases and in general changes to this format should be rare,
because of the impact on upgrade.
+ === Private Stable ===
+    * Incompatible changes allowed at major release (X.0) 
+ Some private interfaces require stability even though they are not documented in the user
documentation and not supported for direct use by the users of Derby, in order for us to guarantee
compatibility across releases.  For instance, the on-disk format for Derby databases must
remain stable across minor releases and in general changes to this format should be rare,
because of the impact on upgrade.
+ === Private Unstable ===
+    * Incompatible changes allowed at minor release (x.Y)
+ This is the same as Unstable, except that the interface is a private interface that is not
documented in the user documentation.
  === Deprecated ===
     * Incompatible change allowed in minor release (x.Y)
@@ -103, +113 @@

  ||Class path requirements||Stable|| || ||
  ||Jar file manifest entires that define external behavior||Stable|| ||e.g. OSGi bundling
now and auto-loading of JDBC driver in the future||
  ||derby.log file format||Unstable|| ||
- ||SQL States returned by Derby SQLExceptions||Stable|| ||
+ ||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||
+ ||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||Stable?|| ||Script writers may require guarantees as to the
location of files within the system||
  ||Tools (ij, dblook, etc.) command-line name and arguments||Stable|| || ||
@@ -119, +132 @@

  ||Undocumented derby properties||Private|| || ||
  ||Network server properties||Stable|| || ||
  == Other notes ==
   * Platform support
      * J2SE 1.3/1.4/1.5 support
@@ -130, +141 @@

   * Derby's versioning of its on-disk database format is described here:
+ == FAQ ==
+ === 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.
+ === 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
+ === Would it be because someone changed some "Standard" interface in an incompatible way
that we move to 11.0? ===
+ If a standards body makes an incompatible change to a standard interface that we rely on,
and we make the choice to upgrade to the new, incompatible revision of that standard, then,
yes, we should move to a new major release.  A standards body making an incompatible change
to a standard should be fairly rare, however.
+ === If no-one made such a change, would be be having 10.14 in a number of years? ===
+ Yes, possibly, unless the community has other reasons to upgrade the version.  Solaris 10
is actually Solaris 2.10.  Solaris has been at the major revision of 2 for over 10 years.

View raw message