Re: [Wonder-disc] incompatile API documentation

[Anjo K. <kr...@lo...>]

Hi David,

Am 21.04.2004 um 18:16 schrieb David Teran:
> When i use a servlet container like tomcat and i switch from version 3 
> to version 4 i would stop using the product if someone tells me: "hey, 
> there are incompatible changes and you are lucky: just read all 
> changes (which are written down using cvs2cl) and after 10 days you 
> hopefully filtered out the important lines ;-) " Same is true for 
> things like eclipse: I am sure that even plugin developer are not 
> reading -every- CVS message just to get an answer why the $*!#!* 
> plugin doesnt work anymore. No, they will read a document or two and 
> know which API was changed without backward compatibility.

These are entirely different products. You normally don't program 
directly against tomcat. And if you used specific features of a servlet 
container, you better check exactly what the release notes say. Same 
with WO. Frankly, I'd be happier if I had the cvs logs of WO, because 
there are a lot of changes that might not seem to matter but will 
certainly break stuff. You *have* to check out your app after a 
framework update. This is not the least bit different with Webobjects.

> Just two places for maybe 10 % of all commit you do because maybe only 
> 10 % break the API: the CVS commit message and the changedAPI file. If 
> this is too much for you i will do it also for your changes because 
> without this documentation wonder will stay in a 'freak' corner like 
> its today which is OK but i would like to see more people using it 
> because it its great and simplifies WO apps a lot.

Again, I think it is a good idea to document all this, but I think an 
extra file to track down is not the way. But as you are willing to do 
keep it up to date, be my guest. In the future, I will flag such 
changes with API: in the commit messages, so they should be easy to 
filter out.

Cheers, Anjo