Summary of votes for Andrew's 3 items

[Andrew R Jaquith <an...@gmail.com>]

Janne pinged me and reminded me that I needed to summarize the votes  
for the three items I put up last week. Here they are. Dirk,  
Christoph, Juan Pablo and Craig (mentor) did not vote.

ITEM 1.
Immediate renaming of all packages from com.ecyrd.jspwiki to  
org.apache.jspwiki, so that we can move to release an early alpha  
Apache build. This would cause all packages currently named  
com.ecyrd.jspwiki to be renamed to org.apache.jspwiki.

Murray: withdrawn (-1?)
Andrew: withdrawn (-1?)
Harry: +0 (?)
Florian: -1
Janne: -1
Christophe: +1

Totals: +1 for, -2 against, 1 neutral, 2 recommendations for  
withdrawals.
Conclusion: Does not pass. In discussions, everyone agreed that the  
rename should happen, but ongoing work by Janne on JCR integration  
will delay this a bit.

ITEM 2.
Refactoring concrete classes (e.g., WikiEngine) into interfaces  
whenever possible, and supplementing them with factory interfaces if  
warranted (e.g., interface WikiEngineFactory).

CLARIFICATION via discussion: extraction would be done with the  
understanding that careful consideration would be given to the methods  
extracted, and to the classes refactored.

Murray: +1
Andrew: +1
Harry: +1
Janne: +0.5 (I think: please let me know if I have misinterpreted)
Florian: +0
Christophe: +0

Totals: ~+3.5 for, 0 against, 2 neutral
Conclusion: this vote passes, unless I've got Janne's vote wrong. I'd  
recommend we move forward with this carefully, and agree on changes  
via group consensus as we go. Janne's comments are well-taken: blind  
refactoring is not the goal here.

ITEM 3.
Creation of the .api package/package tree, and creation of various  
types in this package/package tree (e.g., WikiEngine, WikiPage) for  
stable interfaces.

Murray: -1
Andrew: -1
Harry: -1 (but would like to re-evaluate in a few months)
Janne: +1
Florian: +1
Christophe: +1

Totals: +3 for, -3 against.
Conclusion: As this vote suggests, we have no consensus on this point.  
I'd like a little guidance from our Apache Incubator mentors on how to  
proceed.

Andrew

Re: Summary of votes for Andrew's 3 items

[Janne Jalkanen <Ja...@ecyrd.com>]

> Why not use java annotations to resolve this issue ?

I think that is the right solution to the wrong problem :-)

Annotations don't in this case create any further knowledge that  
would not be visible in the API description itself already...  If we  
had a lot of APIs, then we might benefit from the machine processing  
abilities that annotations would produce, but as it stands, I don't  
think we have that many.  All it means is that the developer will  
need to learn a non-standard way of interpreting our javadoc  
documentation.

/Janne

Re: Summary of votes for Andrew's 3 items

[Dirk Frederickx <di...@gmail.com>]

So far, I didn't got involved nor voted on the ongoing *api pakcage*
discussion as my voice is not much worth compared to all that java-brains on
this mailing list ;-)
Anyway, here is my 2 cents ...

We need to be able to better distinguish *stable* api's from the rest of the
package.
However, by using the java package mechanism, we need to artificially
separate implementation from interface in the source code tree.  This may be
realitvely low-pain, as IDE's seems to provide support for this; but is also
counter-intuitive from a design perspective.


Why not use java annotations to resolve this issue ?

Annotations do not directly affect program semantics, but they allow to add
meta-data to the source-code.

A *@Stable-api* qualifier could provide some kind of meta-data tagging of
the stable java interfaces.
Such an annotation can be treated by tools (apt) to eg generate
documentation or extract classes into eg. API jar.
And it would be very clear to any developer what the status of that
interface is.  But still allow the structure of the source code package tree
be based upon logical design decisions.


WDYT ?


Best whishes for 2009, and let's gear up for the upcoming v3.0.x !
       dirk


On Sun, Jan 4, 2009 at 11:52 AM, Janne Jalkanen <Ja...@ecyrd.com>
wrote:
>>
>> I don't have an answer for how to achieve consensus here. I understand
Murray's point that moving an interface or class is itself disruptive, not
stable. On the other hand, changing the package from ecyrd to apache is
equally disruptive and will need to be done at some point anyway.
>
> Yes, and that is why I proposed that this is done for 3.0, since
everything will break *anyway*.  It would be much easier to tell the
developer that from now on out, the APIs you've been using will be living in
this namespace, and if you stick to that namespace, we'll try really hard to
make sure that your apps don't break.
>
> It's a simple, friendly message, and it gives us the option to move our
internal classes around as much as we please while retaining stability for
plugin developers.
>
> (For example, I would like to move the WikiPage and the rest of the
classes aside from the Release class into org.apache.jspwiki.core to keep
them from polluting the top-level package. This gives a clear indication as
to what they do.)
>
> /Janne

Re: Summary of votes for Andrew's 3 items

[Janne Jalkanen <Ja...@ecyrd.com>]

> I don't have an answer for how to achieve consensus here. I  
> understand Murray's point that moving an interface or class is  
> itself disruptive, not stable. On the other hand, changing the  
> package from ecyrd to apache is equally disruptive and will need to  
> be done at some point anyway.

Yes, and that is why I proposed that this is done for 3.0, since  
everything will break *anyway*.  It would be much easier to tell the  
developer that from now on out, the APIs you've been using will be  
living in this namespace, and if you stick to that namespace, we'll  
try really hard to make sure that your apps don't break.

It's a simple, friendly message, and it gives us the option to move  
our internal classes around as much as we please while retaining  
stability for plugin developers.

(For example, I would like to move the WikiPage and the rest of the  
classes aside from the Release class into org.apache.jspwiki.core to  
keep them from polluting the top-level package. This gives a clear  
indication as to what they do.)

/Janne

Re: Summary of votes for Andrew's 3 items

[Craig L Russell <Cr...@Sun.COM>]

On Jan 3, 2009, at 10:35 AM, Andrew R Jaquith wrote:

> ITEM 3.
> Creation of the .api package/package tree, and creation of various  
> types in this package/package tree (e.g., WikiEngine, WikiPage) for  
> stable interfaces.
>
> Murray: -1
> Andrew: -1
> Harry: -1 (but would like to re-evaluate in a few months)
> Janne: +1
> Florian: +1
> Christophe: +1
>
> Totals: +3 for, -3 against.
> Conclusion: As this vote suggests, we have no consensus on this  
> point. I'd like a little guidance from our Apache Incubator mentors  
> on how to proceed.

It seems to me that the issue is whether to pull all of the proposed  
stable interfaces out of where they currently reside into a new  
location.

I don't have an answer for how to achieve consensus here. I understand  
Murray's point that moving an interface or class is itself disruptive,  
not stable. On the other hand, changing the package from ecyrd to  
apache is equally disruptive and will need to be done at some point  
anyway.

I don't have the high level view of the intended usage of the  
interfaces / base classes, so I won't comment on the technical merits  
for jspwiki. I've seen interfaces used to great effect in other  
projects where the entire interaction with the project was through  
defined, stable interfaces. And as I've mentioned before, subclassing  
gives a lot of flexibility where you don't want to be responsible for  
overriding every behavior of an implementation.

It might be a good exercise for everyone to review what Janne has  
already proposed in the .api package and evaluate whether it's a good  
start or not.

Craig

>
>
> Andrew
>

Craig L Russell
Architect, Sun Java Enterprise System http://db.apache.org/jdo
408 276-5638 mailto:Craig.Russell@sun.com
P.S. A good JDO? O, Gasp!

Re: Summary of votes for Andrew's 3 items

[Janne Jalkanen <Ja...@ecyrd.com>]

> Makes sense, although one of the implications of cutting out  
> WikiEngine from embedding scenarios is that WikiEngine needs to get  
> a lot dumber. WikiEngine would be more of a configuration-holder  
> where you can find references to things (like a page renderer), and  
> less of an all-singing, all-dancing class with convenience methods  
> for everything.

Take a look at the proposed interface in the API package.  It's  
fairly minimal.

It could still be an all-singing all-dancing class, we would just  
have a base class which would provide only the necessary  
functionalities for rendering, then have our own DefaultWikiEngine  
(or whatever) which would then essentially be the current WikiEngine.

> Factories are often useful for creating objects. I did one for  
> WikiContext ("WikiContextFactory"); arguably the PageManager, for  
> example, is or could be a factory class also. Today's WikiEngine  
> serves that role, too -- partly.

I don't like WikiContextFactory; it's just an extra abstraction layer  
for engine.createContext(), and requires a lot more typing.

> One thing we haven't looked at is a generic object-factory e.g.:

I think this is abstracting things too far away.  We need to keep  
things simple and clear, and rotate them around WikiEngine, WikiPage  
and WikiContext.  Everything else is just pretty much scaffolding.

/Janne

Re: Summary of votes for Andrew's 3 items

[Andrew R Jaquith <an...@gmail.com>]

> Note that according to Apache rules, in any code change votes a  
> binding -1 constitutes a veto.  So, this one does not pass.

Ok. Assuming your previous comment about re-wording this proposal  
still stands, I'll re-draft the question and re-submit.

> Craig's point of proper subclassing is a good one and needs to be  
> taken into account.  It might make sense to look whether we can  
> create good abstract subclasses for certain objects (for example,  
> WikiPage actually comes to mind as a good candidate for an abstract  
> base class, since it's mostly an accessor class).  WikiContext is  
> something which probably works well as an interface, but WikiEngine  
> might also be a good base class.

Agreed. Classes that are "big" today, but could be implemented in  
several ways, should have decent abstract base classes. WikiPage would  
be a good one. WikiEngine probably also deserves an abstract base  
class. WikiSession? Probably that too. The proposed interfaces in the  
(just-voted-down) .api package are pretty good starts, though we will  
want to claw back the number of methods in some of them. WikiPlugin/ 
WikiRenderer? I have no opinion on these.

> What I am really aiming is that someone who embeds JSPWiki does not  
> have to start a WikiEngine to get the benefit of JSPWiki rendering  
> engine (there is an open issue for this), but simply provide their  
> own implementations for certain classes (and not low-level ones like  
> Providers, which is the case right now). This means that we need to  
> have either sane default implementations or possibly interfaces for  
> WikiEngine, WikiPage and WikiContext (and redesign some things for  
> PluginManager and VariableManager).

<musing>

Makes sense, although one of the implications of cutting out  
WikiEngine from embedding scenarios is that WikiEngine needs to get a  
lot dumber. WikiEngine would be more of a configuration-holder where  
you can find references to things (like a page renderer), and less of  
an all-singing, all-dancing class with convenience methods for  
everything.

I tend to lean towards the approach of having an interface, plus:
a) an abstract base class + default implementation, OR:
b) a default implementation that is clearly meant to be extended

Factories are often useful for creating objects. I did one for  
WikiContext ("WikiContextFactory"); arguably the PageManager, for  
example, is or could be a factory class also. Today's WikiEngine  
serves that role, too -- partly.

One thing we haven't looked at is a generic object-factory e.g.:

public interface WikiObjectFactory<T>

T create(Class<? extends T> targetType, Object... args);

</musing>

> However, this needs a lot more thinking, and we can't just do it  
> without proper discussion on this subject.

I'm all for it...

Re: Summary of votes for Andrew's 3 items

[Janne Jalkanen <Ja...@ecyrd.com>]

> ITEM 2.
> Refactoring concrete classes (e.g., WikiEngine) into interfaces  
> whenever possible, and supplementing them with factory interfaces  
> if warranted (e.g., interface WikiEngineFactory).
>
> CLARIFICATION via discussion: extraction would be done with the  
> understanding that careful consideration would be given to the  
> methods extracted, and to the classes refactored.
>
> Murray: +1
> Andrew: +1
> Harry: +1
> Janne: +0.5 (I think: please let me know if I have misinterpreted)

I voted -1 against the proposition as written, because I interpret  
calls for votes *literally*.

Note that according to Apache rules, in any code change votes a  
binding -1 constitutes a veto.  So, this one does not pass.

> Conclusion: this vote passes, unless I've got Janne's vote wrong.  
> I'd recommend we move forward with this carefully, and agree on  
> changes via group consensus as we go. Janne's comments are well- 
> taken: blind refactoring is not the goal here.

Craig's point of proper subclassing is a good one and needs to be  
taken into account.  It might make sense to look whether we can  
create good abstract subclasses for certain objects (for example,  
WikiPage actually comes to mind as a good candidate for an abstract  
base class, since it's mostly an accessor class).  WikiContext is  
something which probably works well as an interface, but WikiEngine  
might also be a good base class.

What I am really aiming is that someone who embeds JSPWiki does not  
have to start a WikiEngine to get the benefit of JSPWiki rendering  
engine (there is an open issue for this), but simply provide their  
own implementations for certain classes (and not low-level ones like  
Providers, which is the case right now). This means that we need to  
have either sane default implementations or possibly interfaces for  
WikiEngine, WikiPage and WikiContext (and redesign some things for  
PluginManager and VariableManager).

However, this needs a lot more thinking, and we can't just do it  
without proper discussion on this subject.

/Janne