You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Carsten Ziegeler <cz...@s-und-n.de> on 2004/04/20 10:45:24 UTC
[RT] Versions
In [1] I suggested that we continue the development of 2.1.x and port
some nice things from the 2.2 branch back as long as they don't create
big incompatibilities.
Now, I started to port back the new environment handling and found out
that it's not that easy :)
In the current 2.2 branch we did the following changes at once:
a) update container to fortress
b) change the tree processor
c) remove deprecated code
d) update the environment handling
We did a) and b) to have a better base for the blocks implementation. As
we now follow a different road, these changes are currently not important
for 2.1.x.
Unfortunately, a clean solution for d) depends on c) which means: only
if we remove deprecated code, the environment handling can be
improved. Or in other words: backporting to 2.1.x would require to remove
deprecated classes which could really affect users.
So, I think it's time to think a little bit about versions:
It seems that the general understanding of versions is that a minor
version change (e.g. from 2.1.4 to 2.1.5) is always compatible and
that users in many cases update if a new minor version is released.
A major version change (e.g. from 2.1.x to 2.2) might contain
incompatibilities and it seems that users are reluctant to update.
Following this logic, it would mean that if we would rename the current
2.1.x version that we have in the CVS to 2.2, users would not update
just because of the version name and not the content! So, in fact using
version numbers is a bad idea :) Simply numbering them would be better
(1, 2, 3, ... 1004 etc.)
I think, Stefano mentioned some months ago that the biggest mistake
when starting with the development of Cocoon 2 was the version
change from 1.x to 2.0 and the completly different architecture in 2.0.
So, users couldn't simply update but had to rewrite their app. A
smooth transition would have been better. (I hope my memory is right,
Stefano, I don't want to lay words in your mouth).
Anyways, I totally agree that a smooth transition is a good idea. If we
look at the changes we already did for 2.2, it would have been better
to do them in different steps. This makes development easier and it
makes updating for users easier.
My opinion is that we should remove deprecated classes (some of them)
in our 2.1.x branch *now* in order to create a smooth transition and
to build a better basis for the future development.
To indicate this, we should update the version number to 2.2 *now* in
the cocoon-2.1 repository. This would mean that the next Cocoon
version would be 2.2. If the need for a 2.1.5 arises we could still
make a branch.
We clearly indicate that although we have a major version change,
there are only minor incompatibilities that shouldn't affect users.
Actually this is the hard part! We have to convince users that although
it's a major version change, there shouldn't be a difference between
updating to a fictional 2.1.5 or 2.2. We - as the developers - take
care of this fact. We could create the "Cocoon Version Manifesto".
Removing deprecated code is imho important for users and developers. Of
course, for us developers it makes life easier as it makes
innovations easier and as you don't have to care about some nasty things
anymore. But although users benefit from this as they can use
new features (they are slightly forced to use them :) ). And in addition,
in some cases the support of deprecated interfaces is not done in
a nice way, so deprecated code might not run that smooth and fast
as the non deprecated versions.
We use the current cocoon-2.2 cvs as a scratchpad/sandbox to continue
the blocks development. And if blocks are working, we decide which
version number to use (2.5/3.0/4.0 whatever).
Each time we feel that a major version change is required we simply
do it in the cocoon-2.1 repository. If required, we can make a branch
at any time. The main idea here is that we only have one repository
with the HEAD. Only if required/requested we create a support branch.
Of course, if we follow this road, our repositories would have wrong
names, but this imho doesn't really matter and we could rename the
cocoon-2.2 repository without any problems.
And in addition, 2.2 would be the first release with the official
cocoon forms version. This alone makes a version change acceptable.
WDYT?
Carsten
[1] http://marc.theaimsgroup.com/?t=108222516100003&r=1&w=2
Carsten Ziegeler
Open Source Group, S&N AG
http://www.osoco.net/weblogs/rael/
RE: Proposal: release management guide (was Re: [RT] Versions)
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
Tim Larson wrote:
>
> On Thu, Apr 22, 2004 at 09:50:08PM +0200, Carsten Ziegeler wrote:
> > Tim Larson wrote:
> > > If it happens that 2.3 comes very soon after 2.2, then the
> > > deprecated code in effect was just deleted and not put through a
> > > normal deprecation cycle. Perhaps we need to also set a minimum
> > > length of time that deprecated features will live, to ensure that
> > > deprecation is a meaningful process and not just a formality.
> > >
> > Hmm, yes, this is a valid point. Looking back, it always took some
> > time between our releases, so I think we don't have to set a strict
> > rule for this. We should just decide on a case by case base if the
> > time inbetween releases has been long enough or if we
> should keep the
> > deprecated stuff in the next minor release and remove it one minor
> > release later.
>
> We will need to decide on a case-by-case basis, but we should
> also set a general guideline to help with the decisions.
Ok, we can add this when the guide is in CVS (which should be very
shortly)...
>
> > > Also, we should define what deprecation means, such as whether
> > > simple but severe security issues will receive updates,
> even though
> > > more ongoing or complex updates will not happen to
> deprecated code.
> > Can you please explain this a little bit? Do you mean, what will
> > happen if security issues arise in deprecated code?
>
> Yes, that is what I am asking. If we do not handle security
> issues in deprecated code, our users are not in a much better
> position than if we had just deleted the code without
> deprecation, since they can no longer safely continue to use
> the code in production. If we are going to do the effort of
> a deprecation cycle, we might as well make it mean something
> for our users.
>
Ah, yes, of course. If any severe security issue arises (where 'any' means
either in deprecated or non deprecated code), we will make
a patch release. Yes.
> > Yes, agreed. And we should really start updating libaries only if
> > there is really a good reason for it.
>
> For these compatible releases I agree, but I also appreciate
> Antonio's and others' efforts in keeping these libraries up
> to date. I wish there were an easy way to maintain the
> integration of both old stable and new up-to-date libraries
> against our code.
> I admit I do not know the best, most practical, balance for
> this issue.
>
Yes, in general I personally would always update to the latest
release, but for compatibility it's not always the best choice.
Now, I think Gump is doing this work for us, or? We use a
specific version and Gump builds (and tests?) Cocoon against
the latest version.
Carsten
Re: Proposal: release management guide (was Re: [RT] Versions)
Posted by Tim Larson <ti...@keow.org>.
On Thu, Apr 22, 2004 at 09:50:08PM +0200, Carsten Ziegeler wrote:
> Tim Larson wrote:
> > If it happens that 2.3 comes very soon after 2.2, then the
> > deprecated code in effect was just deleted and not put
> > through a normal deprecation cycle. Perhaps we need to also
> > set a minimum length of time that deprecated features will
> > live, to ensure that deprecation is a meaningful process and
> > not just a formality.
> >
> Hmm, yes, this is a valid point. Looking back, it always took
> some time between our releases, so I think we don't have to
> set a strict rule for this. We should just decide on a case
> by case base if the time inbetween releases has been long
> enough or if we should keep the deprecated stuff in the
> next minor release and remove it one minor release later.
We will need to decide on a case-by-case basis, but we should
also set a general guideline to help with the decisions.
> > Also, we should define what deprecation means, such as
> > whether simple but severe security issues will receive
> > updates, even though more ongoing or complex updates will not
> > happen to deprecated code.
> Can you please explain this a little bit? Do you mean, what
> will happen if security issues arise in deprecated code?
Yes, that is what I am asking. If we do not handle security
issues in deprecated code, our users are not in a much better
position than if we had just deleted the code without deprecation,
since they can no longer safely continue to use the code in
production. If we are going to do the effort of a deprecation
cycle, we might as well make it mean something for our users.
> Yes, agreed. And we should really start updating libaries only
> if there is really a good reason for it.
For these compatible releases I agree, but I also appreciate
Antonio's and others' efforts in keeping these libraries up to
date. I wish there were an easy way to maintain the integration
of both old stable and new up-to-date libraries against our code.
I admit I do not know the best, most practical, balance for this
issue.
--Tim Larson
RE: Proposal: release management guide (was Re: [RT] Versions)
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
Tim Larson wrote:
>
> I am *so* happy to see this policy being worked on :) When I
> earlier proposed we write a document like this the interest
> seemed minimal, so I did not push very hard. Glad to see it
> is gathering steam now.
>
;)
> > 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, 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 it happens that 2.3 comes very soon after 2.2, then the
> deprecated code in effect was just deleted and not put
> through a normal deprecation cycle. Perhaps we need to also
> set a minimum length of time that deprecated features will
> live, to ensure that deprecation is a meaningful process and
> not just a formality.
>
Hmm, yes, this is a valid point. Looking back, it always took
some time between our releases, so I think we don't have to
set a strict rule for this. We should just decide on a case
by case base if the time inbetween releases has been long
enough or if we should keep the deprecated stuff in the
next minor release and remove it one minor release later.
> Also, we should define what deprecation means, such as
> whether simple but severe security issues will receive
> updates, even though more ongoing or complex updates will not
> happen to deprecated code.
Can you please explain this a little bit? Do you mean, what
will happen if security issues arise in deprecated code?
>
> > 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.
>
> I echo Bruno's concern here. If we do an incompatible update
> of a library, and then cocoon starts to rely on the new
> features, then a user cannot just revert the library update
> to get a system as compatible as our versioning scheme would
> indicate we are shipping. To our users and developers it
> would feel like we broke our own versioning rules.
>
> Since *we* are the ones bundling the libraries I think this
> issue is in the scope of Cocoon. If a user were pulling in
> external libraries on their own, then that is what would be
> out of our scope.
>
Yes, agreed. And we should really start updating libaries only
if there is really a good reason for it.
Carsten
Re: Proposal: release management guide (was Re: [RT] Versions)
Posted by Tim Larson <ti...@keow.org>.
On Wed, Apr 21, 2004 at 09:33:14AM +0200, Carsten Ziegeler 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.
I am *so* happy to see this policy being worked on :)
When I earlier proposed we write a document like this the interest
seemed minimal, so I did not push very hard. Glad to see it is
gathering steam now.
> 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,
> 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 it happens that 2.3 comes very soon after 2.2, then the deprecated
code in effect was just deleted and not put through a normal deprecation
cycle. Perhaps we need to also set a minimum length of time that
deprecated features will live, to ensure that deprecation is a
meaningful process and not just a formality.
Also, we should define what deprecation means, such as whether simple
but severe security issues will receive updates, even though more
ongoing or complex updates will not happen to deprecated code.
> 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.
I echo Bruno's concern here. If we do an incompatible update of a
library, and then cocoon starts to rely on the new features, then a user
cannot just revert the library update to get a system as compatible as
our versioning scheme would indicate we are shipping. To our users and
developers it would feel like we broke our own versioning rules.
Since *we* are the ones bundling the libraries I think this issue is in
the scope of Cocoon. If a user were pulling in external libraries on
their own, then that is what would be out of our scope.
--Tim Larson
RE: Proposal: release management guide (was Re: [RT] Versions)
Posted by David Crossley <cr...@apache.org>.
I think that we might mean "manifesto" (noun)
... Macquarie Dictionary:
"a public declaration ... of a body of persons taking
important action, making known intentions, objects,
motives, etc.; a proclamation".
Should it go into cocoon-2.1 CVS so that it travels with the
distribution, or just go into cocoon-site so that it ends
up at the top-level?
Carsten wrote:
> [ADD SOME REASONS WHY WE RECOMMENT RECOMPILATION ANYWAY]
See some notes at http://wiki.cocoondev.org/Wiki.jsp?page=Cocoon215TOC
RE: Proposal: release management guide (was Re: [RT] Versions)
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
Joerg Heinicke wrote:
> > compatible to 2.2. As long as you don't use deprecated API, your
> > application is usage compatible across all minor versions.
>
> Somewhat inaccurate. IMO it must read "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."
>
Thanks, yes, good hint!
Carsten
RE: Proposal: release management guide (was Re: [RT] Versions)
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
Joerg Heinicke wrote:
>
> > This high innovention has - at least in theory - the price of
> > maintaining
>
> innovation + invention = innovention ;-)
>
Ah, you spotted that one. Great :)
But it's not from me:
http://disneyworld.disney.go.com/wdw/parks/attractionDetail?id=InnoventionsE
astAttractionPage
Carsten
Re: Proposal: release management guide (was Re: [RT] Versions)
Posted by Joerg Heinicke <jo...@gmx.de>.
On 21.04.2004 09:33, Carsten Ziegeler wrote:
> 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,
> your application is usage compatible across all minor versions.
Somewhat inaccurate. IMO it must read "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.
Otherwise this would oppose to this example.
> 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.
Let's restrict this to updates of libraries without the need for
touching Cocoon code. This means the user must be able to revert the
update for his local cocoon installation.
> This high innovention has - at least in theory - the price of maintaining
innovation + invention = innovention ;-)
Joerg
Re: Proposal: release management guide (was Re: [RT] Versions)
Posted by Marc Portier <mp...@outerthought.org>.
Reinhard Poetz wrote:
> Carsten Ziegeler wrote:
>
<snip type="large" />
>> 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.
>>
>>
>
> I think we will need *a lot* of testcases to guarentee the compatibility.
>
I agree, however on the sort-term and more pragmatic side of things: all
users out there are a very large test-cases-base, since we're up to
publishing this versioning contract to them we should at least promptly
react when people notice we've not lived up to it. (which should be:
re-introduce promised backwards compat and/or change the version number)
-marc=
--
Marc Portier http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://blogs.cocoondev.org/mpo/
mpo@outerthought.org mpo@apache.org
Re: Proposal: release management guide (was Re: [RT] Versions)
Posted by Reinhard Poetz <re...@apache.org>.
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.
>
>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.
>
>
+1
>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.
>
+1
>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.
>
>
+1
we should make a clear recommendation that recompiling is the better way
>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,
>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.
>
>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.
>
>
+1
>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.
>
>
+1
>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!
>
>
+1
>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.
>
>
I think we as Cocoon project can't avoid problems arising in this
context. So +1
>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.
>
>
I think we will need *a lot* of testcases to guarentee the compatibility.
>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 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.
>
>
+1 again.
So we end in a cocoon-2 (current cocoon-2.1 repository) and a cocoon-3
repository (current cocoon-2.2 repository), don't we?
If we make move to SVN we can correct this naming issue. (It should also
be possible to change this in CVS too - only rename the directory names.
The only disadvantage is that we each CVS user is required to make a
fresh check out.)
--
Reinhard
RE: Proposal: release management guide (was Re: [RT] Versions)
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
Unico Hommes wrote:
>
> For my understanding, what exactly do these terms mean (i.e.
> 'user API'
> and 'developer API') ? Are they paralel to the concepts of
> 'usage compatibility' and 'extension compatibility' or are
> they part of a separate classification?
Yes, they are parallel. Usage compatibility is the compatiblity
of the user api etc.
>
> >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.
> >
> >
> >
>
> Don't you mean ".. removed with the next major or minor release" ?
>
No :) This is the tricky part. I think there are some very very very
very ... very rare cases where it makes sense to just remove some
deprecated stuff between two patch releases. So I don't want to block
this possibility. I will make this more clear in the next
version of this guide.
> >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!
> >
> >
> >
>
> <snip type="more good stuff"/>
>
> As part of the effort of establishing versioning rules and
> consequently the separation of different areas of our code
> base (public, private,
> etc) we could review some of the related proposals that have
> been discussed in the past. Perhaps we could tackle these
> concerns as part of this effort. Especially I am thinking of
> the proposals towards modularisation of the code base into
> functional modules (API, SPI, etc.) and javadoc extensions
> for signalling private or public API membership.
>
> http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=105766229504616&w=2
> http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=106424060330963&w=2
>
Yepp, this has been discussed very often, so perhaps it's really
time to "do something".
Carsten
Re: Proposal: release management guide (was Re: [RT] Versions)
Posted by Unico Hommes <un...@hippo.nl>.
Carsten Ziegeler wrote:
<snip type="lots of good stuff"/>
>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.
>
>
>
For my understanding, what exactly do these terms mean (i.e. 'user API'
and 'developer API') ? Are they paralel to the concepts of 'usage
compatibility' and 'extension compatibility' or are they part of a
separate classification?
>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.
>
>
>
Don't you mean ".. removed with the next major or minor 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!
>
>
>
<snip type="more good stuff"/>
As part of the effort of establishing versioning rules and consequently
the separation of different areas of our code base (public, private,
etc) we could review some of the related proposals that have been
discussed in the past. Perhaps we could tackle these concerns as part of
this effort. Especially I am thinking of the proposals towards
modularisation of the code base into functional modules (API, SPI, etc.)
and javadoc extensions for signalling private or public API membership.
http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=105766229504616&w=2
http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=106424060330963&w=2
--
Unico
Re: Proposal: release management guide (was Re: [RT] Versions)
Posted by Reinhard Poetz <re...@apache.org>.
Upayavira wrote:
> Marc Portier wrote:
>
>>
>>
>> Upayavira wrote:
>>
>>> Carsten,
>>>
>>> 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?
>>>
>>
>> very,
>>
>> I would even suggest (already) that blocks in state 'stable' would
>> maintain an own release numbering scheme which complies to these rules.
>
>
> I thought about this. But, given that they will be released as a part
> of Cocoon, I cannot see how that would work. Unless they are released
> as separate packages that happen independently, they'll need to follow
> Cocoon's versioning system, IMO.
>
> Regards, Upayavira
>
>
I think so too and IIRC this was also the conclusion of a discussion
about the lifecylce of _real_ blocks.
--
Reinhard
Re: Proposal: release management guide (was Re: [RT] Versions)
Posted by Upayavira <uv...@upaya.co.uk>.
Marc Portier wrote:
>
>
> Upayavira wrote:
>
>> Carsten,
>>
>> 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?
>>
>
> very,
>
> I would even suggest (already) that blocks in state 'stable' would
> maintain an own release numbering scheme which complies to these rules.
I thought about this. But, given that they will be released as a part of
Cocoon, I cannot see how that would work. Unless they are released as
separate packages that happen independently, they'll need to follow
Cocoon's versioning system, IMO.
Regards, Upayavira
Re: Proposal: release management guide (was Re: [RT] Versions)
Posted by Marc Portier <mp...@outerthought.org>.
Upayavira wrote:
> Carsten,
>
> 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?
>
very,
I would even suggest (already) that blocks in state 'stable' would
maintain an own release numbering scheme which complies to these rules.
-marc=
--
Marc Portier http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://blogs.cocoondev.org/mpo/
mpo@outerthought.org mpo@apache.org
RE: Proposal: release management guide (was Re: [RT] Versions)
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
Upayavira wrote:
>
>
> Reads very well, I say. All we need to do is decide if that
> is how we actually want to (and can) work!
>
Great! I think we could wait one more day and see if there is
some interesting feedback and then we can vote on it.
> 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?
>
Yes, absolutely. Great!
Carsten
Re: Proposal: release management guide (was Re: [RT] Versions)
Posted by Upayavira <uv...@upaya.co.uk>.
Carsten,
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?
Upayavira
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.
>
>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 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
>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,
>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.
>
>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.
>
>
>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 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
>
>Carsten Ziegeler
>Open Source Group, S&N AG
>http://www.osoco.net/weblogs/rael/
>
>
>
>
RE: Proposal: release management guide (was Re: [RT] Versions)
Posted by Bruno Dumon <br...@outerthought.org>.
On Wed, 2004-04-21 at 09:33, Carsten Ziegeler wrote:
<snip/>
> 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.
If between patch releases we want to keep everything as compatible as
possible, then we shouldn't upgrade external libraries either (except if
known to be completely safe). Otherwise, all the effort we put into
keeping our own stuff compatible could be lost because of that.
>
> 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.
--
Bruno Dumon http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
bruno@outerthought.org bruno@apache.org
RE: Proposal: release management guide (was Re: [RT] Versions)
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
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.
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 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
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,
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.
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.
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 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
Carsten Ziegeler
Open Source Group, S&N AG
http://www.osoco.net/weblogs/rael/
RE: Proposal: release management guide (was Re: [RT] Versions)
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
Marc Portier wrote:
>
> +1
>
> - one extra: when the external lib mismatch can occur, then
> we should provide that knowledge in the update docs and add a warning
Yepp.
>
> -marc= (being glad he posted that arp link :-))
Yes, and I also stole text from your mail :)
>
> <snip
> what="the historical long mail from one eloquent Sir C. Ziegler" />
ROTFL
Carsten
Re: Proposal: release management guide (was Re: [RT] Versions)
Posted by Marc Portier <mp...@outerthought.org>.
+1
- one extra: when the external lib mismatch can occur, then we should
provide that knowledge in the update docs and add a warning
-marc= (being glad he posted that arp link :-))
<snip
what="the historical long mail from one eloquent Sir C. Ziegler" />
--
Marc Portier http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://blogs.cocoondev.org/mpo/
mpo@outerthought.org mpo@apache.org
RE: Proposal: release management guide (was Re: [RT] Versions)
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
Marc Portier wrote:
> here goes:
> I see some difference between what I would call 'extension'
> vs. 'usage'
> compatibility
>
> <snip explains/>
I like the distinction and I totally agree with the vision of
'usage'. In my RT about versions I was only refering to
the 'extension' are when it comes to incompatible changes.
>
> 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)
>
Yes, I think this is really the truth. And in reality things
get very complicated as compatibility for Cocoon as a whole
applies not only to what we develop but to most other projects
we incorporate.
We are - for example - very eager in updating to new releases
of external libraries. So it happens, that we change from
Xalan 2.4 to Xalan 2.6 between 2.1.3 and 2.1.4. (just a fictional
sample). It's a major change for Xalan, so it's not required
to be compatible. But if Cocoon or a users application relies
on some things that have changed between 2.4 and 2.6, then
Cocoon isn't compatible between 2.1.3 and 2.1.4 for them. And
of course, they blame Cocoon (which isn't soo wrong).
And in fact, these updates to the external libraries cause a
lot of problems to users when they try to update from one
version to another of Cocoon.
So, what do we do with all these infos?
Carsten
Proposal: release management guide (was Re: [RT] Versions)
Posted by Marc Portier <mp...@outerthought.org>.
Carsten Ziegeler wrote:
> Marc Portier wrote:
>>in general I'm all for a more formal description of the
>>meaning of versions to us.
>>
>>something like: http://apr.apache.org/versioning.html but
>>probably more focussed towards Java classes, interfaces, xml
>>schema's and namespaces ?
>>
>>from there we could probably formulate some guidelines
>>towards associating code maintenance actions like
>>- bugfixing
>>- deprectation
>>- addition
>>- removal
>>
>>and how that is reflected in our cvs management towards
>>- tagging
>>- branching/merging
>>- new repository
>>
>>
>
> Yes, good idea!
>
> Do I understand you correctly that you are volunteering? Great :)
>
not really: I was hoping somebody was going to direct me to the URL of
the existing ones that could end my confusion :-)
in any case I'm not too shy to start this thread, and see where a joint
effort can bring us, I'm not the guy that wants everything carved in
stone, on the other hand it seems such a waste of time to discuss and
re-evaluate this kind of stuff on a case per case...
here goes:
I see some difference between what I would call 'extension' vs. 'usage'
compatibility
'usage' compatibility would be the guarantee that my xml files (elements
and namespace declarations) keep on being picked up by the machinery and
dealth with correctly (sitemap semantics, generator/transformer-picked
up elements, config file entries...)
it seems logic that this can grow, but should however remain backwards
compatible over the various minor releases of the same major release
parts of this usage we want to deprecate could be flagged through
run-time warnings to logger.warn() but remain supported (this would
indicate that an upcoming major release will no longer support this)
'extension' compatibility would be the guarantee that my own extensions
to what cocoon provides (own java classes that interface directly with
protected/package/public members in our distribution, and maybe also my
own javascript code that depends on cocoon provided library-functions)
maintaining these over various minor releases seems more then we need,
so keeping these stable within the scope of one minor release (ie across
the various patch-releases) should do. This would mean that parts of
that intreface can get deprecated but no additions/removals could happen.
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)
comments welcome,
-marc=
--
Marc Portier http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://blogs.cocoondev.org/mpo/
mpo@outerthought.org mpo@apache.org
RE: [RT] Versions
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
Marc Portier wrote:
>
> Carsten Ziegeler wrote:
>
> <snip />
>
> > And in addition, 2.2 would be the first release with the official
> > cocoon forms version. This alone makes a version change acceptable.
> >
>
> do you already have a timeframe in mind?
> (cforms is still unstable, and is IMO not near removing that tag)
>
Oh, that's bad. I don't have a timeframe in mind. I had a timeframe
in mind for 2.1.5 (end of march/beginning of april), but due to the
licensing problems it's currently not possible to release :(
So, currently I'm waiting for those problems to get solved and then
we can think about a timeframe. But regardless of that, I think
we should get a new release out asap.
> > WDYT?
> >
>
> in general I'm all for a more formal description of the
> meaning of versions to us.
>
> something like: http://apr.apache.org/versioning.html but
> probably more focussed towards Java classes, interfaces, xml
> schema's and namespaces ?
>
> from there we could probably formulate some guidelines
> towards associating code maintenance actions like
> - bugfixing
> - deprectation
> - addition
> - removal
>
> and how that is reflected in our cvs management towards
> - tagging
> - branching/merging
> - new repository
>
>
Yes, good idea!
Do I understand you correctly that you are volunteering? Great :)
Carsten
Re: [RT] Versions
Posted by Marc Portier <mp...@outerthought.org>.
Carsten Ziegeler wrote:
<snip />
> And in addition, 2.2 would be the first release with the official
> cocoon forms version. This alone makes a version change acceptable.
>
do you already have a timeframe in mind?
(cforms is still unstable, and is IMO not near removing that tag)
> WDYT?
>
in general I'm all for a more formal description of the meaning of
versions to us.
something like: http://apr.apache.org/versioning.html but probably more
focussed towards Java classes, interfaces, xml schema's and namespaces ?
from there we could probably formulate some guidelines towards
associating code maintenance actions like
- bugfixing
- deprectation
- addition
- removal
and how that is reflected in our cvs management towards
- tagging
- branching/merging
- new repository
regards,
-marc=
> Carsten
>
> [1] http://marc.theaimsgroup.com/?t=108222516100003&r=1&w=2
>
> Carsten Ziegeler
> Open Source Group, S&N AG
> http://www.osoco.net/weblogs/rael/
>
--
Marc Portier http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://blogs.cocoondev.org/mpo/
mpo@outerthought.org mpo@apache.org
RE: [RT] Versions
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
Hi,
yes, you're right - it's my fault this time, I used the terms in
a different meaning. So, if you read this thread and replace
"minor" with "patch" and "major" with "minor", we use the general
meaning :) Sorry!
BTW, I'm currently working on a first draft of the guide.
Carsten
> -----Original Message-----
> From: Andreas Hochsteger [mailto:e9625392@student.tuwien.ac.at]
> Sent: Tuesday, April 20, 2004 10:51 PM
> To: dev@cocoon.apache.org
> Subject: Re: [RT] Versions
>
> I'm a bit confused about the naming of version number parts.
> I always thought, that version numbers are constructed like this:
> MAJOR.MINOR.PATCH
>
> I did some quick google search and found the following pages
> which seem to confirm that:
> http://apr.apache.org/versioning.html#strategy
> http://www.linuxcertified.com/e-learning/linuxplus/html/1_9.html
> http://www.elego-software-solutions.com/man/committing-and-rel
easing.html
> http://edocs.bea.com/wles/docs41/javadocs/JavaAPI/com/bea/secu
> rity/ServiceVersion.html
> http://protodesign-inc.com/doc/SansGUI/class_schema_version_contro.htm
> http://www-unix.mcs.anl.gov/~gawor/jglobus-nightly/doc/org/glo
bus/common/Version.html
>
> In the last discussion about version numbers (it was before
> the introduction of the cocoon-2.2 repository) there were the
> same misunderstandings as I already pointed out here:
> http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=105959008920632&w=2
>
> Sorry to be that picky again, but it's hard to follow the
> discussions if different people mean different things by
> using the same words.
>
> A versioning guide - like Marc already suggests - would be
> really helpful to make these things clear.
>
> Andreas.
>
>
> Reinhard Poetz schrieb:
>
> > Carsten Ziegeler wrote:
> >
> >> Reinhard Poetz wrote:
> >>
> >>
> >>> Carsten Ziegeler wrote:
> >>>
> >>>
> >>>
> >>>> <snip/>
> >>>>
> >>>>
> >>>> My opinion is that we should remove deprecated classes (some
> >>>
> >>> of them)
> >>>
> >>>> in our 2.1.x branch *now* in order to create a smooth
> >>>
> >>> transition and to
> >>>
> >>>> build a better basis for the future development.
> >>>> To indicate this, we should update the version number to 2.2
> >>>
> >>> *now* in
> >>>
> >>>> the cocoon-2.1 repository. This would mean that the next
> >>>
> >>> Cocoon version
> >>>
> >>>> would be 2.2. If the need for a 2.1.5 arises we could
> still make a
> >>>> branch.
> >>>> We clearly indicate that although we have a major version
> >>>
> >>> change, there
> >>>
> >>>> are only minor incompatibilities that shouldn't affect users.
> >>>>
> >>>>
> >>>>
> >>>
> >>> Who is affected by those changes? What does an upgrade
> mean for the
> >>> user?
> >>>
> >>>
> >>
> >> Good question, thanks Reinhard, I forgot to tell that :)
> >>
> >> If we remove deprecated classes, users that have developed their
> >> application for Cocoon 2.0.x are affected if they are
> still using the
> >> deprecated classes. If your app is developed for Cocoon 2.1.x, you
> >> are not affected.
> >>
> >>
> >
> > Following this, why do we need a version change to 2.2 if
> 'only' 2.0
> > users, who want to upgrade, are affected. The change from
> 2.0 to 2.1
> > was a major version change which _can_ cause some minor
> incombatibilites.
> >
> >> An upgrade for a user means that she just has to replace
> the use of
> >> the deprecated class with a newer one. So it comes down to using a
> >> different interface name and a different method name in some rare
> >> cases. The two areas affected here are caching and source
> resolving.
> >> In both cases, using the new interfaces provides improved features
> >> but also improved performance and stability anyway.
> >>
> >> Another area are the RequestLifeCycle components. They have been
> >> introduced in Cocoon 2.0.4 (I think) and we have voted to
> remove them
> >> in 2.2 again. So if you are using them, you have to use one of the
> >> alternatives which is using Contextualizable to get the
> object model
> >> or the RequestDataStore to store infos. But I guess that
> not many are
> >> using these interfaces anyway.
> >>
> >> I would add of course documents on how to update for each area.
> >>
> >>
> >
> > Same as above.
> >
> > IMO we can move on with 2.1.x and remove the depracated classes if
> > this is necessary. WDYT?
> >
> >
>
>
Re: [RT] Versions
Posted by Andreas Hochsteger <e9...@student.tuwien.ac.at>.
I'm a bit confused about the naming of version number parts.
I always thought, that version numbers are constructed like this:
MAJOR.MINOR.PATCH
I did some quick google search and found the following pages which seem
to confirm that:
http://apr.apache.org/versioning.html#strategy
http://www.linuxcertified.com/e-learning/linuxplus/html/1_9.html
http://www.elego-software-solutions.com/man/committing-and-releasing.html
http://edocs.bea.com/wles/docs41/javadocs/JavaAPI/com/bea/security/ServiceVersion.html
http://protodesign-inc.com/doc/SansGUI/class_schema_version_contro.htm
http://www-unix.mcs.anl.gov/~gawor/jglobus-nightly/doc/org/globus/common/Version.html
In the last discussion about version numbers (it was before the
introduction of the cocoon-2.2 repository) there were the same
misunderstandings as I already pointed out here:
http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=105959008920632&w=2
Sorry to be that picky again, but it's hard to follow the discussions if
different people mean different things by using the same words.
A versioning guide - like Marc already suggests - would be really
helpful to make these things clear.
Andreas.
Reinhard Poetz schrieb:
> Carsten Ziegeler wrote:
>
>> Reinhard Poetz wrote:
>>
>>
>>> Carsten Ziegeler wrote:
>>>
>>>
>>>
>>>> <snip/>
>>>>
>>>>
>>>> My opinion is that we should remove deprecated classes (some
>>>
>>> of them)
>>>
>>>> in our 2.1.x branch *now* in order to create a smooth
>>>
>>> transition and to
>>>
>>>> build a better basis for the future development.
>>>> To indicate this, we should update the version number to 2.2
>>>
>>> *now* in
>>>
>>>> the cocoon-2.1 repository. This would mean that the next
>>>
>>> Cocoon version
>>>
>>>> would be 2.2. If the need for a 2.1.5 arises we could still make a
>>>> branch.
>>>> We clearly indicate that although we have a major version
>>>
>>> change, there
>>>
>>>> are only minor incompatibilities that shouldn't affect users.
>>>>
>>>>
>>>>
>>>
>>> Who is affected by those changes? What does an upgrade mean for the
>>> user?
>>>
>>>
>>
>> Good question, thanks Reinhard, I forgot to tell that :)
>>
>> If we remove deprecated classes, users that have developed their
>> application for Cocoon 2.0.x are affected if they are still
>> using the deprecated classes. If your app is developed for
>> Cocoon 2.1.x, you are not affected.
>>
>>
>
> Following this, why do we need a version change to 2.2 if 'only' 2.0
> users, who want to upgrade, are affected. The change from 2.0 to 2.1 was
> a major version change which _can_ cause some minor incombatibilites.
>
>> An upgrade for a user means that she just has to replace the
>> use of the deprecated class with a newer one. So it comes
>> down to using a different interface name and a different
>> method name in some rare cases. The two areas affected here are
>> caching and source resolving.
>> In both cases, using the new interfaces provides improved
>> features but also improved performance and stability anyway.
>>
>> Another area are the RequestLifeCycle components. They have
>> been introduced in Cocoon 2.0.4 (I think) and we have voted
>> to remove them in 2.2 again. So if you are using them,
>> you have to use one of the alternatives which is
>> using Contextualizable to get the object model or the
>> RequestDataStore to store infos. But I guess that not
>> many are using these interfaces anyway.
>>
>> I would add of course documents on how to update for each area.
>>
>>
>
> Same as above.
>
> IMO we can move on with 2.1.x and remove the depracated classes if this
> is necessary. WDYT?
>
>
Re: [RT] Versions
Posted by Antonio Gallardo <ag...@agssa.net>.
Reinhard Poetz dijo:
> IMO we can move on with 2.1.x and remove the deprecated classes if this
> is necessary. WDYT?
+1
Best Regards,
Antonio Gallardo
RE: [RT] Versions
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
Marc Portier wrote:
>
> Hm, I think I'm swinging towards the observations you made in
> opening this thread.
>
> We seem to have grown some implicit meaning (expectations)
> around these version numbers, I don't think we should ignore that...
>
> I'm not the kind of guy that wants everything formalized but
> it does seem meaningful to solidify some position and avoid
> to reconsider again and again, no?
>
Yes, that would be the best solution.
Carsten
Re: [RT] Versions
Posted by Marc Portier <mp...@outerthought.org>.
Carsten Ziegeler wrote:
> Reinhard Poetz wrote:
>
<snip />
>>IMO we can move on with 2.1.x and remove the depracated
>>classes if this is necessary. WDYT?
>>
>
> To be honest, this was my first thinking as well :) But there is
> the general perception that a minor version change is 100%
> compatible (or 99.9%) which is of course not the case if we
> remove deprecated classes.
> If noone is against it, we can continue with the 2.1.x - sure.
> This would makes thinks easier.
>
Hm, I think I'm swinging towards the observations you made in opening
this thread.
We seem to have grown some implicit meaning (expectations) around these
version numbers, I don't think we should ignore that...
I'm not the kind of guy that wants everything formalized but it does
seem meaningful to solidify some position and avoid to reconsider again
and again, no?
-marc=
--
Marc Portier http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://blogs.cocoondev.org/mpo/
mpo@outerthought.org mpo@apache.org
RE: [RT] Versions
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
Reinhard Poetz wrote:
>
> Following this, why do we need a version change to 2.2 if
> 'only' 2.0 users, who want to upgrade, are affected. The
> change from 2.0 to 2.1 was a major version change which _can_
> cause some minor incombatibilites.
>
> >An upgrade for a user means that she just has to replace the
> use of the
> >deprecated class with a newer one. So it comes down to using a
> >different interface name and a different method name in some rare
> >cases.
> >The two areas affected here are caching and source resolving.
> >In both cases, using the new interfaces provides improved
> features but
> >also improved performance and stability anyway.
> >
> >Another area are the RequestLifeCycle components. They have been
> >introduced in Cocoon 2.0.4 (I think) and we have voted to
> remove them
> >in 2.2 again. So if you are using them, you have to use one of the
> >alternatives which is using Contextualizable to get the
> object model or
> >the RequestDataStore to store infos. But I guess that not many are
> >using these interfaces anyway.
> >
> >I would add of course documents on how to update for each area.
> >
> >
>
> Same as above.
>
> IMO we can move on with 2.1.x and remove the depracated
> classes if this is necessary. WDYT?
>
To be honest, this was my first thinking as well :) But there is
the general perception that a minor version change is 100%
compatible (or 99.9%) which is of course not the case if we
remove deprecated classes.
If noone is against it, we can continue with the 2.1.x - sure.
This would makes thinks easier.
Carsten
Re: [RT] Versions
Posted by Reinhard Poetz <re...@apache.org>.
Carsten Ziegeler wrote:
>Reinhard Poetz wrote:
>
>
>>Carsten Ziegeler wrote:
>>
>>
>>
>>><snip/>
>>>
>>>
>>>My opinion is that we should remove deprecated classes (some
>>>
>>>
>>of them)
>>
>>
>>>in our 2.1.x branch *now* in order to create a smooth
>>>
>>>
>>transition and to
>>
>>
>>>build a better basis for the future development.
>>>To indicate this, we should update the version number to 2.2
>>>
>>>
>>*now* in
>>
>>
>>>the cocoon-2.1 repository. This would mean that the next
>>>
>>>
>>Cocoon version
>>
>>
>>>would be 2.2. If the need for a 2.1.5 arises we could still make a
>>>branch.
>>>We clearly indicate that although we have a major version
>>>
>>>
>>change, there
>>
>>
>>>are only minor incompatibilities that shouldn't affect users.
>>>
>>>
>>>
>>>
>>Who is affected by those changes? What does an upgrade mean
>>for the user?
>>
>>
>>
>Good question, thanks Reinhard, I forgot to tell that :)
>
>If we remove deprecated classes, users that have developed their
>application for Cocoon 2.0.x are affected if they are still
>using the deprecated classes. If your app is developed for
>Cocoon 2.1.x, you are not affected.
>
>
Following this, why do we need a version change to 2.2 if 'only' 2.0
users, who want to upgrade, are affected. The change from 2.0 to 2.1 was
a major version change which _can_ cause some minor incombatibilites.
>An upgrade for a user means that she just has to replace the
>use of the deprecated class with a newer one. So it comes
>down to using a different interface name and a different
>method name in some rare cases.
>The two areas affected here are caching and source resolving.
>In both cases, using the new interfaces provides improved
>features but also improved performance and stability anyway.
>
>Another area are the RequestLifeCycle components. They have
>been introduced in Cocoon 2.0.4 (I think) and we have voted
>to remove them in 2.2 again. So if you are using them,
>you have to use one of the alternatives which is
>using Contextualizable to get the object model or the
>RequestDataStore to store infos. But I guess that not
>many are using these interfaces anyway.
>
>I would add of course documents on how to update for each area.
>
>
Same as above.
IMO we can move on with 2.1.x and remove the depracated classes if this
is necessary. WDYT?
--
Reinhard
RE: [RT] Versions
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
Reinhard Poetz wrote:
>
> Carsten Ziegeler wrote:
>
> ><snip/>
> >
> >
> >My opinion is that we should remove deprecated classes (some
> of them)
> >in our 2.1.x branch *now* in order to create a smooth
> transition and to
> >build a better basis for the future development.
> >To indicate this, we should update the version number to 2.2
> *now* in
> >the cocoon-2.1 repository. This would mean that the next
> Cocoon version
> >would be 2.2. If the need for a 2.1.5 arises we could still make a
> >branch.
> >We clearly indicate that although we have a major version
> change, there
> >are only minor incompatibilities that shouldn't affect users.
> >
> >
>
> Who is affected by those changes? What does an upgrade mean
> for the user?
>
Good question, thanks Reinhard, I forgot to tell that :)
If we remove deprecated classes, users that have developed their
application for Cocoon 2.0.x are affected if they are still
using the deprecated classes. If your app is developed for
Cocoon 2.1.x, you are not affected.
An upgrade for a user means that she just has to replace the
use of the deprecated class with a newer one. So it comes
down to using a different interface name and a different
method name in some rare cases.
The two areas affected here are caching and source resolving.
In both cases, using the new interfaces provides improved
features but also improved performance and stability anyway.
Another area are the RequestLifeCycle components. They have
been introduced in Cocoon 2.0.4 (I think) and we have voted
to remove them in 2.2 again. So if you are using them,
you have to use one of the alternatives which is
using Contextualizable to get the object model or the
RequestDataStore to store infos. But I guess that not
many are using these interfaces anyway.
I would add of course documents on how to update for each area.
Carsten
Re: [RT] Versions
Posted by Reinhard Poetz <re...@apache.org>.
Carsten Ziegeler wrote:
><snip/>
>
>
>My opinion is that we should remove deprecated classes (some of them)
>in our 2.1.x branch *now* in order to create a smooth transition and
>to build a better basis for the future development.
>To indicate this, we should update the version number to 2.2 *now* in
>the cocoon-2.1 repository. This would mean that the next Cocoon
>version would be 2.2. If the need for a 2.1.5 arises we could still
>make a branch.
>We clearly indicate that although we have a major version change,
>there are only minor incompatibilities that shouldn't affect users.
>
>
Who is affected by those changes? What does an upgrade mean for the user?
--
Reinhard
Re: [RT] Versions
Posted by Marc Portier <mp...@outerthought.org>.
Carsten Ziegeler wrote:
> Joerg Heinicke wrote:
>
<snip />
>>Now the confusion starts. IMO we should have clear
>>version/repository matchings.
>>
>
> Yes, a clear matching is required. We would have the clear matching
> of "Any cocoon version >= 2.1 is in the cocoon-2.1 repository" :)
>
LOL.
>
>>>Of course, if we follow this road, our repositories would
>>
>>have wrong
>>
>>>names, but this imho doesn't really matter and we could rename the
>>>cocoon-2.2 repository without any problems.
>>
>>I don't agree. This naming issue really matters. It's IMO
>>much more important than non-upgrades during project's
>>lifetime. If we follow the proposal the above cries for a
>>cocoon-2 repository (the current 2.1) to make this at least clear.
>>And each branch is moved into a new repository.
>
> Now, actually, I didn't want to get into the "repository vs. branches
> and naming" discussions :) Ok, but we don't need to make a repository
> just because we change the version number. It only makes sense
agree
> if we continue the development. We end up in to many repositories
> that are actually unused.
> I don't see any problem with branching a previous version if
> the need arises.
>
agree, we should learn the lesson of the repository names we gave, not
let them prevent us from doing a proper release management
-marc=
--
Marc Portier http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://blogs.cocoondev.org/mpo/
mpo@outerthought.org mpo@apache.org
RE: [RT] Versions
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
Joerg Heinicke wrote:
>
> On 20.04.2004 12:28, Carsten Ziegeler wrote:
>
> >>On the other hand I didn't get the feeling that there were many
> >>problems when upgrading from 2.0 to 2.1. This might be due to not
> >>upgrading at all of course.
> >>Probably users start a project with a specific Cocoon version/the
> >>latest release at this time. During the project they do
> only the minor
> >>upgrades. When starting the next project they use the
> latest available
> >>version at that time again. So upgrade problems might be
> only rarely
> >>reported.
> >
> > There were many complains from users that upgrading from
> 2.0.x to 2.1
> > wasn't that easy.
>
> Really? I never got this impression. On the list or from your
> customers?
>From our lists (mostly from the user list).
Carsten
Re: [RT] Versions
Posted by Joerg Heinicke <jo...@gmx.de>.
On 20.04.2004 12:28, Carsten Ziegeler wrote:
>>On the other hand I didn't get the feeling that there were
>>many problems when upgrading from 2.0 to 2.1. This might be
>>due to not upgrading at all of course.
>>Probably users start a project with a specific Cocoon
>>version/the latest release at this time. During the project
>>they do only the minor upgrades. When starting the next
>>project they use the latest available version at that time
>>again. So upgrade problems might be only rarely reported.
>
> There were many complains from users that upgrading from 2.0.x
> to 2.1 wasn't that easy.
Really? I never got this impression. On the list or from your customers?
Not that this will have any impact on the result of this discussion ...
just curious.
> Yes, a clear matching is required. We would have the clear matching
> of "Any cocoon version >= 2.1 is in the cocoon-2.1 repository" :)
*prust* really good.
Renaming it without any impact should even possible with CVS. Otherwise
we can wait til the move to SVN.
> Ok, but we don't need to make a repository
> just because we change the version number. It only makes sense
> if we continue the development. We end up in to many repositories
> that are actually unused.
> I don't see any problem with branching a previous version if
> the need arises.
Ok, convinced - and this lazy branching is much better than the eager
branching we have at the moment.
Joerg
RE: [RT] Versions
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
Joerg Heinicke wrote:
>
>
> > only
> > if we remove deprecated code, the environment handling can be
> > improved. Or in other words: backporting to 2.1.x would require to
> > remove deprecated classes which could really affect users.
>
> What does "remove deprecated classes" mean? I guess only the
> usage of them or not? The classes itself can stay where they
> are (or moved to src/deprecated or whatever).
>
See my answer to Reinhard's question for more info. In addition:
no, it's not possible to just remove the usage in all cases as
for example for the source resolving we changed the interface
and removed deprecated methods.
>
> > Following this logic, it would mean that if we would rename the
> > current 2.1.x version that we have in the CVS to 2.2, users
> would not
> > update just because of the version name and not the content!
>
> IMO we should just make clear that the 2.1 => 2.2 upgrade is
> not that major than 2.0 => 2.1. But that's only true if we
> release the first version of 2.2 short after the fork from 2.1.
>
Yes.
> On the other hand I didn't get the feeling that there were
> many problems when upgrading from 2.0 to 2.1. This might be
> due to not upgrading at all of course.
> Probably users start a project with a specific Cocoon
> version/the latest release at this time. During the project
> they do only the minor upgrades. When starting the next
> project they use the latest available version at that time
> again. So upgrade problems might be only rarely reported.
There were many complains from users that upgrading from 2.0.x
to 2.1 wasn't that easy.
>
> > To indicate this, we should update the version number to
> 2.2 *now* in
> > the cocoon-2.1 repository. This would mean that the next Cocoon
> > version would be 2.2. If the need for a 2.1.5 arises we could still
> > make a branch.
>
> Now the confusion starts. IMO we should have clear
> version/repository matchings.
>
Yes, a clear matching is required. We would have the clear matching
of "Any cocoon version >= 2.1 is in the cocoon-2.1 repository" :)
> > Of course, if we follow this road, our repositories would
> have wrong
> > names, but this imho doesn't really matter and we could rename the
> > cocoon-2.2 repository without any problems.
>
> I don't agree. This naming issue really matters. It's IMO
> much more important than non-upgrades during project's
> lifetime. If we follow the proposal the above cries for a
> cocoon-2 repository (the current 2.1) to make this at least clear.
> And each branch is moved into a new repository.
Now, actually, I didn't want to get into the "repository vs. branches
and naming" discussions :) Ok, but we don't need to make a repository
just because we change the version number. It only makes sense
if we continue the development. We end up in to many repositories
that are actually unused.
I don't see any problem with branching a previous version if
the need arises.
> But not not
> the stuff is branched out, but only the old one. This would
> make it consistent with the current cocoon-2.0 and make an
> upgrade easier for people living from CVS. This also means a
> 2.2 release would result in a cocoon-2.1 repository as
> quasi-branch point.
Checking out a branch or a tagged version from CVS is as easy as
checking out the head.
Carsten
Re: [RT] Versions
Posted by Joerg Heinicke <jo...@gmx.de>.
Carsten Ziegeler <cziegeler <at> s-und-n.de> writes:
> WDYT?
Hmm, sorry, but that's to much confusion IMO. But read on ...
<snip what="changes 2.1 => 2.2"/>
> only
> if we remove deprecated code, the environment handling can be
> improved. Or in other words: backporting to 2.1.x would require to remove
> deprecated classes which could really affect users.
What does "remove deprecated classes" mean? I guess only the usage of them or
not? The classes itself can stay where they are (or moved to src/deprecated or
whatever).
> So, I think it's time to think a little bit about versions:
>
> It seems that the general understanding of versions is that a minor
> version change (e.g. from 2.1.4 to 2.1.5) is always compatible and
> that users in many cases update if a new minor version is released.
Yes, this is also my impression from reading the users list. But we are not
always completely compatible, so there are often some minor issues.
> A major version change (e.g. from 2.1.x to 2.2) might contain
> incompatibilities and it seems that users are reluctant to update.
That's naturally I think.
> Following this logic, it would mean that if we would rename the current
> 2.1.x version that we have in the CVS to 2.2, users would not update
> just because of the version name and not the content!
IMO we should just make clear that the 2.1 => 2.2 upgrade is not that major than
2.0 => 2.1. But that's only true if we release the first version of 2.2 short
after the fork from 2.1.
On the other hand I didn't get the feeling that there were many problems when
upgrading from 2.0 to 2.1. This might be due to not upgrading at all of course.
Probably users start a project with a specific Cocoon version/the latest release
at this time. During the project they do only the minor upgrades. When starting
the next project they use the latest available version at that time again. So
upgrade problems might be only rarely reported.
> So, in fact using
> version numbers is a bad idea :) Simply numbering them would be better
> (1, 2, 3, ... 1004 etc.)
I don't think so. The hierarchy versioning helps in deciding whether to do an
upgrade or not.
> Anyways, I totally agree that a smooth transition is a good idea.
I don't agree here. Maybe users would not upgrade at all because they fear there
are more incompatibilities with every minor release.
I also do not see a problem when users do not upgrade from one major to another
major version during a project's time.
> To indicate this, we should update the version number to 2.2 *now* in
> the cocoon-2.1 repository. This would mean that the next Cocoon
> version would be 2.2. If the need for a 2.1.5 arises we could still
> make a branch.
Now the confusion starts. IMO we should have clear version/repository matchings.
> Removing deprecated code is imho important for users and developers.
+1 in general of course.
> We use the current cocoon-2.2 cvs as a scratchpad/sandbox to continue
> the blocks development. And if blocks are working, we decide which
> version number to use (2.5/3.0/4.0 whatever).
> Each time we feel that a major version change is required we simply
> do it in the cocoon-2.1 repository. If required, we can make a branch
> at any time. The main idea here is that we only have one repository
> with the HEAD. Only if required/requested we create a support branch.
>
> Of course, if we follow this road, our repositories would have wrong
> names, but this imho doesn't really matter and we could rename the
> cocoon-2.2 repository without any problems.
I don't agree. This naming issue really matters. It's IMO much more important
than non-upgrades during project's lifetime. If we follow the proposal the above
cries for a cocoon-2 repository (the current 2.1) to make this at least clear.
And each branch is moved into a new repository. But not not the stuff is
branched out, but only the old one. This would make it consistent with the
current cocoon-2.0 and make an upgrade easier for people living from CVS. This
also means a 2.2 release would result in a cocoon-2.1 repository as quasi-branch
point.
> And in addition, 2.2 would be the first release with the official
> cocoon forms version. This alone makes a version change acceptable.
+1 you need valueable additionals/features.
Joerg