You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@cocoon.apache.org by da...@cocoon.zones.apache.org on 2006/08/01 14:21:53 UTC
[DAISY] Created: The Apache Cocoon Versioning Manifesto - DRAFT
A new document has been created.
http://cocoon.zones.apache.org/daisy/documentation/1181.html
Document ID: 1181
Branch: main
Language: default
Name: The Apache Cocoon Versioning Manifesto - DRAFT
Document Type: Cocoon Document
Created: 8/1/06 12:21:42 PM
Creator (owner): Helma van der Linden
State: publish
Parts
=====
Content
-------
Mime type: text/xml
Size: 11687 bytes
Content:
<html>
<body>
<p class="warn">DRAFT INITIAL VERSION</p>
<p>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.</p>
<h1>Basics</h1>
<p>Versions are denoted using a standard triplet of integers:</p>
<p>MAJOR.MINOR.PATCH.</p>
<p>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.</p>
<p>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.</p>
<p>A developer codes Java and provides additional functionality for the user, so
a developer extends Cocoon.</p>
<p>Therefore we distinguish between usage compatibility (user API) and extension
compatibility (developer API). 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
safer to compile your own application code (if any) using the version of Cocoon
that your application runs on.</p>
<p>There are several reasons why recompilation is recommended. We strongly
advise to compile Cocoon (or any other Java application) with the same JDK that
is later used in production.</p>
<ul>
<li>Ensures that you have reliable operating environment. For example if you
compile a Java application with JDK 1.4 in JDK 1.3 compatible mode it still can
happen that your application doesn't run properly with JDK 1.3! This is not
Cocoon specific!</li>
<li>Allows you to easily configure which parts you want. The selection of wanted
blocks is currently evaluated at build time, so if you want to have an
additional block/remove a block in your Cocoon installation, you have to rebuild
Cocoon.</li>
<li>You will get warned about deprecated parts of the API.</li>
</ul>
<h1>Usage Compatibility</h1>
<p><em>Usage</em> 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...).</p>
<p>In fact this should cover everything (including flow script) but except your
own Java code.</p>
<p>Applications that write against a particular version will remain usage
compatible against later versions, until the major number changes.</p>
<p>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 necessarily usage compatible to
2.1, although it is usage compatible to 2.2. As long as you don't use deprecated
API (and the API you rely on does not get deprecated), your application is usage
compatible across all minor versions.</p>
<p>Example:</p>
<ul>
<li>a feature is introduced in 2.0 and used by the application.</li>
<li>it is deprecated in 2.2</li>
<li>it will be removed in 2.3</li>
</ul>
<p>If the time inbetween two minor releases is very short, then it might happen
that deprecated parts will be kept in the following minor release and are
removed in a follow-up minor release. This is in order to ensure that users have
time to update their applications if they use the deprecated parts.</p>
<p>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.</p>
<h1>Extension Compatibility</h1>
<p><em>extension</em> compatibility guarantees that your own extensions to what
Cocoon provides (your Java classes that interface directly with API in the
Cocoon distribution) compile and operate.</p>
<p>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 their
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.</p>
<p>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.</p>
<h1>Deprecation and Exceptions</h1>
<p>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.</p>
<p>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.</p>
<p>If a part of the developer API is deprecated it will be removed with the next
major, minor or patch release. However, the need for removing deprecated stuff
between two patch releases is really very rare and will only happen if the cost
of keeping it is much higher than the cost that might occur from updating the
application.</p>
<p>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!</p>
<h1>Blocks and Block Stability</h1>
<p>Cocoon currently allows optional functionality to be included or excluded
using a simple system called blocks, in which the functionality is included or
excluded at compile time.</p>
<p>[NB. This is a precursor to a more complete block system which is currently
under development.]</p>
<p>A block can have one of three statuses: unstable, stable or deprecated. An
unstable block has an API that can change without notice. A stable block is
subject to the same versioning process as described in this document. Similarly,
when the entire functionality of a block is deprecated, it will be handled in
the same way as any other deprecated code within Cocoon.</p>
<h1>External Libraries</h1>
<p>Cocoon uses a set of external libraries (like for example Avalon, Xalan or
Xerces). Between any release, even patch releases, the versions of the external
libraries might be updated to any version. Cocoon only updates external
libraries if there are good reasons for it, like important bug fixes or new
features that will be used by the new Cocoon version.</p>
<p class="note">TODO: Should we mention the testing framework?</p>
<p>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.</p>
<p>The documentation of Cocoon contains a list of the libraries and the version
changes between libraries from one Cocoon release to another.</p>
<h1>Examples</h1>
<p>Here are some examples to demonstrate the compatibility:</p>
<table>
<tbody>
<tr>
<th>
<p>Original Version</p>
</th>
<th>
<p>New Version</p>
</th>
<th>
<p>Usage Compatible</p>
</th>
<th>
<p>Extension Compatible</p>
</th>
</tr>
<tr>
<td>
<p>2.2.3</p>
</td>
<td>
<p>2.2.4</p>
</td>
<td>
<p>Yes</p>
</td>
<td>
<p>Yes</p>
</td>
</tr>
<tr>
<td>
<p>2.2.3</p>
</td>
<td>
<p>2.3.1</p>
</td>
<td>
<p>Yes</p>
</td>
<td>
<p>No</p>
</td>
</tr>
<tr>
<td>
<p>2.2.3</p>
</td>
<td>
<p>3.0.0</p>
</td>
<td>
<p>No</p>
</td>
<td>
<p>No</p>
</td>
</tr>
</tbody>
</table>
<p>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.</p>
<h1>Versioning and Repositories</h1>
<p>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.
</p>
<p>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.</p>
<p>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 versions.
</p>
<p>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 repository 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.</p>
<p>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.</p>
<p>In addition Cocoon has a sandbox repository to test new features.</p>
<h1>Reality</h1>
<p>The above expresses the intentions of the Cocoon community to support a
release management contract to all the users of the framework. However reality
observes that the path to hell is paved with good intentions. In case anyone
finds clear violation or signs of potential problems of these good intentions,
please report those to the mailing lists or issue tracker so that proper action
can be taken (which might be reverting some changes and/or assigning a different
version number).</p>
<p>If you have read this, you might get the impression that updating your
application from one Cocoon to another one will be very time consuming. Or that
we are acting arbitrarily in deprecating stuff here and there.</p>
<p>Of course this is not the case :) Before we introduce new features, new API
we discuss this in great detail, so this should reduce potential errors in the
design to a minimum. In addition, deprecating stuff is also handled with great
care. So, in the end, this guide establishes rules that detail how we handle
such rare situations. It is not a free ticket for the Cocoon developers to
deprecate/change/remove stuff as they want.</p>
</body>
</html>
Collections
===========
The document belongs to the following collections: generaldocs