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>