Harry -- Lately I haven't been sleeping as much -- it's true. :)
Fixing the unit tests has been very helpful -- but not just because the tests run better now. It's helped identify functionality gaps, and has uncovered some interesting bugs. For example, fixing the ReferenceManager tests prompted a rewrite that used JCR, which in turn uncovered a very subtle encoding bug in Priha. Other bugs that were uncovered by fixing the unit tests: problems with pageExists(); parsing problems with wiki spaces that caused links to be interepreted as interwiki links; a bug in JCRWikiPage.isAttachment(); dozens of NPEs etc etc... So yeah, we fixed lots of tests, but more importantly fixed lots of BUGS. :) The core code base is in much, much better shape than it was 60 days ago. Andrew On Tue, May 12, 2009 at 12:37 PM, Harry Metske <[email protected]> wrote: > I don't feel qualified enough to interfere with the design discussions, but > I do want stress the importance of a good set of working JUnit tests, and > that it should be the first thing to fix, saving us a lot of time in the > next steps (designing/coding/testing). > So, for that part, many credits to Andrew, I really sometimes wonder if you > ever sleep :-) > > Another thing, I don't have a clear view on the general use of JSPWiki, is > the majority just installing it in their AppServer and using it as is, or is > there a serious crowd out there embedding JSPWiki in something else and > really using the API's we have had some many discussions on. > So I can't really judge on the importance on having this clear and high > quality public (Java-level) API. > > Maybe it would be good to describe some use cases ? > > regards, > Harry > > 2009/5/12 Janne Jalkanen <[email protected]> > >> >>> With respect to event-firing, it cannot be a matter of taste. From a >>> JCR node lifecycle standpoint, we need certain events to fire at >>> particular times. In JSPWiki, this always happens from inside manager >>> classes, and so ContentManager is clearly the right place to fire node >>> events. How could it not be? For page saves, here are the options we >>> have: >>> >> >> I don't, frankly, give a crap who fires events and where. It's all internal >> code. >> >> But I *do* care about presenting a simple interface to developers (as >> opposed to committers). APIs should be our "first class citizens" and we >> should have a clear, concise API instead of hundreds of classes and >> thousands of methods which are all lumped together with the instructions >> "just read the javadocs, and oh, we've documented the ones which you're not >> supposed to use, except that we mostly haven't." >> >> Committers and contributors are expected to know the internal structure and >> know which should be logically placed where. Developers aren't. And forcing >> them to wade through hundreds of pages of Javadoc documentation, no matter >> how good, is akin to learning a new language. And that is not good. >> >> Because of the way Java works, we are forced to make some methods public in >> some classes, even though most of the time those should not be public, but >> somehow limited to "classes of org.apache.wiki only". The fact that a >> method is public does not mean that it should be callable by a developer. >> You can say that those methods should be documented, but I am saying that >> *most* of the methods that we have are like that. >> >> I do appreciate the desire to abstract interactions with >>> ContentManager away from plugin developers. From the standpoint of >>> "making it easy for developers to do common things easily," it does >>> simplify things to have WikiPage.save(). So I take your point on this, >>> and to that end we should remove the @deprecated annotation from >>> WikiPage.save(). >>> >> >> Look, I quite spent some time trying to figure out what would be a nice and >> common API towards developers. My *new* code for 3.0 gets @deprecated for no >> reason and replaced without any discussion whatsoever. My suggestion for an >> API package and a simplified developer offering is a "non-starter" and >> that's pretty much the extent of the discussion. >> >> So is it any wonder I get a bit brusque about it? >> >> We need to talk more about what we're doing and where we're planning to >> take this thing. Getting unit tests to run is admirable (and thank you for >> it), but it is not enough. No unit tests and source control are substitutes >> for developer discussion. >> >> I, for one, want to see our developer offering simplified, and I've >> provided the api package as a suggestion on how that should be handled. I do >> believe that it would be good to split our offering to a "jspwiki-api.jar" >> and "jspwiki.jar", so that we can exert stronger change control to the >> classes and interfaces in jspwiki-api.jar, which gives a) committers freedom >> to change internal code more radically, if needed, and b) give the third >> parties and developers something that they can grasp easily, build their >> stuff on top of, and rely on so that they don't have to rewrite all plugins >> moving from 3.0 to 3.1. >> >> /Janne >> >
