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
