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:35:52 GMT
Janne,

This discussion has brought back some issues that we need to discuss
further, like the API package. That is something best worked through
in person, perhaps the next time you are in Boston. Our last
face-to-face was immensely productive.

I also favor more regular communications amongst the core dev team. We
have a lot to do before 3.0 is ready. I am open to suggestions. Skype
conferencing perhaps? I will have irregular dev patterns for the next
month or so (getting married), but after July 1 I'll be on a more
regular schedule.

That said, I had hoped to get some signal from you about the right
strategy for solving the particular issue I described. Although you
did not say so explicitly in your reply, I'll interpret what you wrote
as meaning option #2. That is, remove the @deprecated annotation from
WikiPage.save(), and add guidance to the method docs requiring
implementors to call ContentManager.save(). The concrete
implementation in JCRWikiPage.save(), which already delegates to
ContentManager, can stay as-is -- it's all opaque to callers anyway.

Reasonable?

Andrew

On Tue, May 12, 2009 at 3:07 AM, Janne Jalkanen
<Janne.Jalkanen@ecyrd.com> wrote:
>>
>> 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