cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tim Larson <>
Subject Re: Proposal: release management guide (was Re: [RT] Versions)
Date Wed, 21 Apr 2004 13:49:08 GMT
On Wed, Apr 21, 2004 at 09:33:14AM +0200, Carsten Ziegeler wrote:
> The Cocoon Versioning Manifest (CVM)
> ------------------------------------
> This document covers how the Cocoon project is versioned. 
> Since Cocoon is a framework, it is very important to define 
> a stable API for users and developers. However, we also need 
> to move Cocoon forward, technologically. To balance these two 
> needs, a strict policy of versioning is required, which users 
> can rely upon to understand the limitations, restrictions, 
> and the changes that can occur from one release to the next.

I am *so* happy to see this policy being worked on :)
When I earlier proposed we write a document like this the interest
seemed minimal, so I did not push very hard.  Glad to see it is
gathering steam now.

> Applications that write against a particular version will remain
> usage compatible against later versions, until the major number 
> changes.
> Writing an application against a version means that this application
> does not use any deprecated API of that version. Therefore minor 
> version changes are only usage compatible from one minor version to 
> the direct following one. For example 2.2 is usage compatible to 2.1.
> But 2.3 is not necessary usage compatible to 2.1, although it is 
> usage compatible to 2.2. As long as you don't use deprecated API,
> your application is usage compatible across all minor versions.
> Example: 
> - a feature is introduced in 2.0 and used by the application.
> - it is deprecated in 2.2.
> - it will be removed in 2.3.

If it happens that 2.3 comes very soon after 2.2, then the deprecated
code in effect was just deleted and not put through a normal deprecation
cycle.  Perhaps we need to also set a minimum length of time that
deprecated features will live, to ensure that deprecation is a
meaningful process and not just a formality.

Also, we should define what deprecation means, such as whether simple
but severe security issues will receive updates, even though more
ongoing or complex updates will not happen to deprecated code.

> External Libraries
> ------------------
> Cocoon uses a set of external libraries (like for example Avalon, 
> Xalan or Xerces). Inbetween any release, even patch releases,
> the versions of the external libraries might be updated to any version.
> Therefore if your application is written against a special API of an 
> external library it might be that this API of the external library 
> changes inbetween two Cocoon versions and therefore your application 
> does not work properly anymore (or even does not compile anymore).
> Unfortunately, this issue is out of the scope of Cocoon.

I echo Bruno's concern here.  If we do an incompatible update of a
library, and then cocoon starts to rely on the new features, then a user
cannot just revert the library update to get a system as compatible as
our versioning scheme would indicate we are shipping.  To our users and
developers it would feel like we broke our own versioning rules.

Since *we* are the ones bundling the libraries I think this issue is in
the scope of Cocoon.  If a user were pulling in external libraries on
their own, then that is what would be out of our scope.

--Tim Larson

View raw message