Mailing-List: contact dev-help@cocoon.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cocoon.apache.org
Message-ID: <408845B5.2050403@upaya.co.uk>
Date: Thu, 22 Apr 2004 23:22:45 +0100
From: Upayavira <uv@upaya.co.uk>
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US;
 rv:1.4) Gecko/20030624
MIME-Version: 1.0
To: dev@cocoon.apache.org
Subject: Re: [vote] Versioning Guide
References: <OFCF89E03E.8E36F59D-ONC1256E7E.006D4DCA@sundn.de>
In-Reply-To: <OFCF89E03E.8E36F59D-ONC1256E7E.006D4DCA@sundn.de>
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Transfer-Encoding: 7bit

Minor details, no doubt, but in principle +1.

Upayavira

Carsten Ziegeler wrote:

>Appended is the first version of the versioning guide. I 
>incorporated all changes/comments that have been made to
>it on the list (at least that's what I hope I did...).
>
>Now, this is a first version that we can expand over time.
>In addition some native speakers or people that are able
>to write understandable english (so not me) should review
>the guide once we added it to our cvs.
>
>So, I think we should vote now for the general tendency
>outlined in the guide and not on every detail. If the guide
>is accepted, we add it to our CVS, update it, change
>details that perhaps might not be appropriate/correct and 
>then try to follow it as good as we can.
>
>Here is my +1 (of course) :)
>
>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.
>
>Basics
>------
>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 (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 saver to compile your own application code (if
>any) using the version of Cocoon that your application runs on.
>[ADD SOME REASONS WHY WE RECOMMENT RECOMPILATION ANYWAY]
>
>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 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 (and the API you
>rely on does not get deprecated), 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 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.
>
>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. 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 for updating the application. 
>
>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!
>
>Blocks and Block Stability
>--------------------------
>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.
>
>[NB. This is a precursor to a more complete block system which is currently
>under development.]
>
>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.
>
>
>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.
>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.
>
>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.
>
>The documentation of Cocoon contains a list of the libraries and the
>version changes between libraries from one Cocoon release to another.
>
>
>Examples
>--------
>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
>versions. 
>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.
>
>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 
>
>Carsten Ziegeler 
>Open Source Group, S&N AG
>http://www.osoco.net/weblogs/rael/
>
>
>  
>