You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by up...@apache.org on 2005/04/27 12:07:12 UTC
svn commit: r164967 [3/3] - in
/cocoon/whiteboard/doc-repos/global/src/content/xdocs: ./ OLD-achives/
OLD-committer/ OLD-committers/ OLD-contrib/ OLD-devinfo-merge-to-committer/
OLD-fr-mail-lists/ OLD-francais/ OLD-history/ OLD-hosting/ OLD-incubation/
OLD-index/ OLD-links/ OLD-livesites-1.x/ OLD-livesites-2.0/
OLD-livesites-2.1/ OLD-mail-archives/ OLD-mail-lists/ OLD-news/ OLD-pmc/
OLD-releasing/ OLD-versioning/
Added: cocoon/whiteboard/doc-repos/global/src/content/xdocs/OLD-versioning/content_en.html
URL: http://svn.apache.org/viewcvs/cocoon/whiteboard/doc-repos/global/src/content/xdocs/OLD-versioning/content_en.html?rev=164967&view=auto
==============================================================================
--- cocoon/whiteboard/doc-repos/global/src/content/xdocs/OLD-versioning/content_en.html (added)
+++ cocoon/whiteboard/doc-repos/global/src/content/xdocs/OLD-versioning/content_en.html Wed Apr 27 03:07:09 2005
@@ -0,0 +1,364 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>The Apache Cocoon Versioning Manifesto - DRAFT</title>
+<link href="http://purl.org/DC/elements/1.0/" rel="schema.DC">
+</head>
+<body>
+
+<div class="warning">DRAFT INITIAL VERSION</div>
+
+
+<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>
+<!-- TODO: Should we mention the testing framework? -->
+
+<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>Exsamples</h1>
+
+
+<p>
+ Here are some examples to demonstrate the compatibility:
+ </p>
+<!-- TODO: Change the format: -->
+
+<pre class="code">
+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
+ </pre>
+
+<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>
Added: cocoon/whiteboard/doc-repos/global/src/content/xdocs/OLD-versioning/meta.xml
URL: http://svn.apache.org/viewcvs/cocoon/whiteboard/doc-repos/global/src/content/xdocs/OLD-versioning/meta.xml?rev=164967&view=auto
==============================================================================
--- cocoon/whiteboard/doc-repos/global/src/content/xdocs/OLD-versioning/meta.xml (added)
+++ cocoon/whiteboard/doc-repos/global/src/content/xdocs/OLD-versioning/meta.xml Wed Apr 27 03:07:09 2005
@@ -0,0 +1,9 @@
+<?xml version="1.0"?>
+<meta>
+ <authors>
+ <author contact="http://cocoon.apache.org">Cocoon Community</author>
+ </authors>
+ <legacy>
+ <original-filename>versioning.html</original-filename>
+ </legacy>
+</meta>
Modified: cocoon/whiteboard/doc-repos/global/src/content/xdocs/site.xml
URL: http://svn.apache.org/viewcvs/cocoon/whiteboard/doc-repos/global/src/content/xdocs/site.xml?rev=164967&r1=164966&r2=164967&view=diff
==============================================================================
--- cocoon/whiteboard/doc-repos/global/src/content/xdocs/site.xml (original)
+++ cocoon/whiteboard/doc-repos/global/src/content/xdocs/site.xml Wed Apr 27 03:07:09 2005
@@ -68,4 +68,38 @@
<xml.apache.org href="http://xml.apache.org/"/>
</external-refs>
+ <legacy label="Legacy" tab="legacy">
+ <link label="link">
+ <doc label="livesites-1.x" href="OLD-livesites-1.x.html"/>
+ <doc label="livesites-2.1" href="OLD-livesites-2.1.html"/>
+ <doc label="hosting" href="OLD-hosting.html"/>
+ <doc label="livesites-2.0" href="OLD-livesites-2.0.html"/>
+ <doc label="index" href="OLD-links.html"/>
+ </link>
+ <doc label="versioning" href="OLD-versioning.html"/>
+ <community label="community">
+ <doc label="incubation" href="OLD-incubation.html"/>
+ <doc label="mail-lists" href="OLD-mail-lists.html"/>
+ <doc label="members" href="OLD-committers.html"/>
+ <doc label="contrib" href="OLD-contrib.html"/>
+ <doc label="committer" href="OLD-committer.html"/>
+ <doc label="mail-archives" href="OLD-mail-archives.html"/>
+ </community>
+ <fr label="fr">
+ <doc label="mail-lists" href="OLD-fr-mail-lists.html"/>
+ <doc label="index" href="OLD-francais.html"/>
+ </fr>
+ <doc label="whoweare" href="OLD-pmc.html"/>
+ <news label="news">
+ <doc label="archives" href="OLD-achives.html"/>
+ <doc label="index" href="OLD-news.html"/>
+ </news>
+ <devinfo label="devinfo">
+ <doc label="releasing" href="OLD-releasing.html"/>
+ <doc label="index" href="OLD-devinfo-merge-to-committer.html"/>
+ </devinfo>
+ <doc label="index" href="OLD-index.html"/>
+ <doc label="history" href="OLD-history.html"/>
+ </legacy>
+
</site>
Modified: cocoon/whiteboard/doc-repos/global/src/content/xdocs/tabs.xml
URL: http://svn.apache.org/viewcvs/cocoon/whiteboard/doc-repos/global/src/content/xdocs/tabs.xml?rev=164967&r1=164966&r2=164967&view=diff
==============================================================================
--- cocoon/whiteboard/doc-repos/global/src/content/xdocs/tabs.xml (original)
+++ cocoon/whiteboard/doc-repos/global/src/content/xdocs/tabs.xml Wed Apr 27 03:07:09 2005
@@ -37,5 +37,6 @@
<tab id="tutorials" label="Tutorials" href="http://brutus.apache.org/docs/build/cocoon-2-2/getting-started.html"/>
<tab id="docs" label="Documentation" href="http://brutus.apache.org/docs/build/cocoon-2-2/index.html"/>
<tab id="blocks" label="Blocks" href="http://brutus.apache.org/docs/build/cocoon-2-2/blocks.html"/>
+ <tab id="legacy" label="Legacy" dir="" indexfile="OLD-index.html"/>
</tabs>