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] Trivial Update of "ModuleVersioningGuidelines" by DavidVanCouvering
Date Thu, 22 Sep 2005 05:05:00 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/ModuleVersioningGuidelines

------------------------------------------------------------------------------
  
  Review comments for these guidelines can be created, viewed and responded to at ModuleVersioningGuidelinesReview
  
- This document describes our guidelines around modules in Derby that are shared across multiple
consumers, either internally or externally to Derby.  As of this writing, the only module
like this is the proposed common components module (see [http://issues.apache.org/jira/browse/DERBY-289
 DERBY-289])
+ This document describes our guidelines around modules in Derby, where a module is a group
of one or more packages made available as an cohesive unit which can be shared across multiple
consumers, either internally or externally to Derby.  As of this writing, the only module
like this is the proposed common code module (see [http://issues.apache.org/jira/browse/DERBY-289
 DERBY-289])
  
  These guidelines are based on the [http://jakarta.apache.org/commons/releases/versioning.html
Jakarta Runtime Versioning Guidelines].  There are some areas that these guidelines do not
cover, however, which we will address here:
+ 
+    * Mixed Version support
+ 
+    * Version publishing and detection
  
     * Guidelines for forward-compatibility
  
     * Deprecation guidelines and mechanisms
  
+ == Mixed Version Support ==
+ 
+ As much as possible, two applications should be able to use different versions of Derby
code within the same Java VM without having to resort to creating specialized classloaders.
 This is enabled by supporting forward compatibility as described below.  
+ 
+ == Version Publishing and Detection ==
+ 
+ Every module must provide access to its version information through a static method that
returns an instance of `org.apache.derby.iapi.services.ProductVersionHolder`.  
+ 
+ '''Note''' - I would like to migrate `ProductVersionHolder` and the other classes in the
`info` package to `org.apache.derby.common.info` as they are already shared across tools,
client, DRDA and engine.
+ 
  == Guidelines for Forward Compatibility ==
  
- It is important that shareable modules are as interoperable as possible across versions.
 This includes a new consumer of an interface being able to work with an old implementation.
 Wherever possible, version X.Y of a consumer should work with version X.Y' of a module where
Y' < Y.  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 module (rather than an obtuse Java exception like `NoSuchMethodException`).
+ It is important that shareable modules are as interoperable as possible across versions.
 This includes not just backward compatibility but also forward compatibility.  
  
+ Wherever possible, a consumer built against version X.Y of a module should work with version
X.Y' of a module where Y' < Y.  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 module (rather than an obtuse Java exception like `NoSuchMethodException`).
 The consumer takes adavantage of the version detection mechanism described above to query
the version of the module and then take appropriate action.
- To enable this type of detection and behavior degradation, every module must provide access
to its version information through a static method that returns an instance of `org.apache.derby.iapi.services.ProductVersionHolder`.
 A consumer can then use this information to determine whether it is compatible with the module
or if it needs to either degrade its behavior or throw an exception.
- 
- '''Note''' - I would like to migrate `ProductVersionHolder` and the other classes in the
`info` package to `org.apache.derby.common.info` as they are already shared across tools,
client, DRDA and engine.
  
  === Deprecation Guidelines ===
  A method or an interface may be deprecated.  This is done using the @deprecated tag in the
method or interface Javadoc.  A method or interface must be available for 2 major releases
after it is deprecated.  For example, if it is deprecated in version 8.2, it can be removed
in version 10.0 or greater.  An exception to this rule may occur if it becomes clear that
there is still heavy use of this interface.

Mime
View raw message