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 "SharedComponentVersioningGuidelines" by DavidVanCouvering
Date Thu, 20 Oct 2005 00:04:02 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/SharedComponentVersioningGuidelines

------------------------------------------------------------------------------
  
  == Guidelines for Forward Compatibility ==
  
- In general, a consumer built against version X.Y of a shared component should work with
version X.Y' of a module where Y' < Y.  This is called ''forward compatibility''.
+ In general, a consumer built against version X.Y of a shared component should work with
version X.Y' of a module where Y' < Y.  This is called ''forward compatibility''.  
  
  If the consumer uses new functionality added in version X.Y of the module, it should degrade
to X.Y' level functionality.  In the ''rare cases'' where this is not achievable, the consumer
should throw an exception explaining that it requires version X.Y or greater of the shared
component (rather than an obtuse Java exception like `NoSuchMethodException`).  
+ 
+ Forward compatibility should be guaranteed between patch revisions (from X.Y.Z to X.Y.Z')
and minor revisions (from X.Y to X.Y').  We should strive for forward compatibility between
major releases, but it is not a guarantee.
  
  The consumer decides it can work with a given version of a shared component not by looking
up its version number and then extrapolating what features are available, but instead by directly
querying the component to see if the shared component provides the feature or features it
is looking for.  
  
@@ -89, +91 @@

     * Packages contained within the component
     * The name of the Info class that provides the hasFeature() method
  
+ == User Visible Impact and Restrictions ==
+ 
+ With these guidelines in place, there should in general be visible impact or restrictions
for Derby users.  The only exception is if for some reason (and this is to be avoided) a change
is made between major revisions that is not compatible, then if the user is running in a mixed
version environment in the same VM, he or she should attempt to ensure that the jar files
from the newer version are loaded first.  If for some reason this is not possible, the user
will need to separate the two versions by using separate classloaders within the same VM.
+ 
+ == Testing Impact ==
+ 
+ In the first new release after common components are introduced, we will want to test for
compatibility between patch and minor releases in the following ways:
+ 
+   * Build common component unit tests against the new release and test against jar files
from old releases (backward compatibility tests)
+   * Build common component unit tests from old releases and test against jar files from
the new release (forward compatibility tests)
+ 
+ Any incompatibilities between patch and minor releases should be considrered bugs.  Any
incompatibilities between major releases should be documented.
+  
  == Introducing New Shared Components and Shared Packages ==
  
  When a developer wishes to introduce a new shared component or a new package within an existing
shared component, this should be put up for a vote.  This is to help ensure that what we are
sharing makes sense and does not accidentally paint us into some kind of architectural corner.
 Adding new classes or methods to an existing shared package does not need to be put up for
a vote but should be reviewed using the standard patch review mechanism.

Mime
View raw message