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
