<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
