Mailing-List: contact derby-commits-help@db.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Derby Development" <derby-dev@db.apache.org>
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: Apache Wiki <wikidiffs@apache.org>
To: derby-commits@db.apache.org
Date: Thu, 22 Sep 2005 04:52:32 -0000
Message-ID: <20050922045232.9250.91163@ajax.apache.org>
Subject: [Db-derby Wiki] Trivial Update of "ModuleVersioningGuidelines" by
 DavidVanCouvering

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 clients, 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 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])
  
  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:
  
@@ -14, +14 @@

  
  == Guidelines for Forward Compatibility ==
  
- It is important that shareable modules are as interoperable as possible across versions.  This includes a new client of an interface being able to work with an old implementation.  Wherever possible, version X.Y of a client should work with version X.Y' of a module where Y' < Y.  If the client 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, it 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 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`).
  
- 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 client 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.
+ 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.