incubator-jspwiki-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Andrew Jaquith <andrew.r.jaqu...@gmail.com>
Subject Re: svn commit: r773455 - in /incubator/jspwiki/trunk: ./ src/java/org/apache/wiki/ src/java/org/apache/wiki/api/ src/java/org/apache/wiki/content/ src/java/org/apache/wiki/parser/ src/java/org/apache/wiki/plugin/ src/java/org/apache/wiki/search/ src
Date Tue, 12 May 2009 19:52:20 GMT
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 <harry.metske@gmail.com> 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 <Janne.Jalkanen@ecyrd.com>
>
>>
>>> 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
>>
>

Mime
View raw message