cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Carsten Ziegeler" <>
Subject RE: Proposal: release management guide (was Re: [RT] Versions)
Date Wed, 21 Apr 2004 07:33:14 GMT
Marc Portier wrote: 
> I currently don't think we have a release scheme that 
> supports one or the other: i.e. reality seems pretty much 
> like what Carsten is saying: 
> we just have 1,2,... 1004 (based on some gut feeling we seem 
> to be distributing those numbers over tripplets)
I thought about this topic a little bit and I can only say we
never followed any compatibility rules! For example we changed
the sitemap in an incompatible way not only from 2.0.x to 2.1,
but also from 2.1.3 to 2.1.4.
And we removed deprecated API/changed interfaces/methods 
between patch releases.

So following this "logic", we could just follow this road and do
whatever we think is appropriate or establish some general and
simple rules to make the live of the users easier.

I have written a first draft of such a guide (well I copied some
things from here and there and added my two cents). So, let's
start another flame war and tell me what you think about this.

(PS: I think this one of the longest mails I ever 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.

Versions are denoted using a standard triplet of integers: 
MAJOR.MINOR.PATCH. The basic intent is that MAJOR versions are 
incompatible, large-scale upgrades of the API. MINOR versions 
retain usage and extension compatibility with older minor versions, 
and changes in the PATCH level are perfectly compatible, forwards 
and backwards.

Following the main design principle of Cocoon, the pyramid
of contracts, we distinguish between users and developers
of Cocoon.
A very rough distinction between them is that a user writes
the application using Cocoon without coding Java. There is
one exception to this rule: flow script - the java script
is also written by the user.
A developer codes Java and provides additional functionality
for the user, so a developer extends Cocoon.

Therefore we distinguish between usage compatibility and
extension compatibility. Both compatibility levels cover
some kind of "source" compatibility. Cocoon does not provide
binary compatibility. But as Cocoon is distributed as a
source release that you have to compile anyway, it's
saver to compile your own application code (if any) using
the version of Cocoon that your application runs on.

Usage Compatibility

'Usage' compatibility guarantees that an application written 
by a Cocoon user is compatible. All files developed by a typical 
Cocoon user like xml files, sitemaps, stylesheets (elements and 
namespace declarations) keep on being picked up by the machinery 
and are dealt with correctly (sitemap semantics, 
generator/transformer-picked up elements, config file entries...). 
In fact this should cover everything (including flow script) but 
except own Java code.

Applications that write against a particular version will remain
usage compatible against later versions, until the major number 
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.

- 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.

However, if an application uses an API which has become available 
in a particular minor version, it (obviously) will no longer 
operate against previous minor versions.

Extension Compatibility

'extension' compatibility guarantees that own extensions to what
Cocoon provides (own Java classes that interface directly with 
API in the Cocoon distribution) compile and operate.

Applications that write against a particular version will remain
extension compatible against later versions until the major or 
the minor number changes (Please note the difference to the usage
compatibility). However, the Cocoon developers take care that even 
if the minor number changes, most of the own code still works and 
operates properly. Incompatible changes between minor versions are 
kept to a minimum. Frequent new releases of Cocoon ensure that 
developers have a smooth transition path.

If an interface/class changes in an incompatible way between minor
version changes, the Cocoon documentation will contain a detailed 
update guide that contains a solution for every incompatible change.
So following this guide should make the update smoothly.

Deprecation and Exceptions

To continue the Cocoon development and to keep up with the innovations,
parts of Cocoon might get deprecated; this includes parts of the user
API and also parts of the developer API.

If a part of the user API is deprecated, this will be flagged through 
run-time warnings that appear in the logs but remain supported. This
indicates that an upcoming minor (or major) release will no longer 
support this.

If a part of the developer API is deprecated it will be removed with 
the next major, minor or patch release.

For developers there is one exception to this rule: private API. Cocoon
has some internal classes and interfaces that are not meant to be used
by a Cocoon developer (someone extending Cocoon). These pieces of
Java code are clearly marked in the Javadocs and should not be used.
They might change even between a patch version change in an incompatible
way without providing a workaround!

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.

Here are some examples to demonstrate the compatibility:

Original Version    New Version    Usage Compatible    Extension Compatible
2.2.3                  2.2.4          Yes                      Yes
2.2.3                  2.3.1          Yes                      No
2.2.3                  3.0.0          No                       No

Note: while some of the cells say "no", it is possible that the versions 
may be compatible, depending very precisely upon the particular APIs 
used by the application.

Versioning and Repositories
Cocoon is very innovative and new features are added very frequently. This
results in new functionality that justify a minor version change on its own.
In addition, to move Cocoon forward technologically, some features have
to be removed/deprecated which of course results in a minor version change
as well.

So, Cocoon will potentially release several versions with minor version
changes in a year and only a few patch releases. Of course, if a patch
release is required, for example if a potential security issue is found
etc., the patch release will be made available asap.

This high innovention has - at least in theory - the price of maintaining
several branches at once in order to be able to apply patches to older
To reduce this to a minimum, Cocoon uses one repository per major version.
The HEAD of the repository always contains the latest version. If a new
minor release is required, the version in the CVS is directly changed
to this minor version (e.g. from 2.1.4 to 2.2). The current state is
tagged and if the need for a 2.1.5 release arises, a branch is created.

However, due to the compatibility rules explained above, there should only
be a reason for a patch version if major problems occur (like security
issues). In any other case, the Cocoon community expects the applications
to migrate to the new minor version release which should be fairly simple.

In addition Cocoon has a sandbox repository to test new features.


Carsten Ziegeler 
Open Source Group, S&N AG

View raw message