cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Upayavira>
Subject Re: Proposal: release management guide (was Re: [RT] Versions)
Date Wed, 21 Apr 2004 11:24:34 GMT

Reads very well, I say. All we need to do is decide if that is how we 
actually want to (and can) work!

One addition is to mention our policy on blocks and block status:

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.


Does this seem reasonable?


Carsten Ziegeler wrote:

>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