incubator-jspwiki-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Janne Jalkanen <Janne.Jalka...@ecyrd.com>
Subject Re: Other 2.6.2 changes
Date Wed, 07 May 2008 17:07:07 GMT

Yes, I can certainly see what the issue here is - we are lacking some  
"big picture" documentation.  The Javadocs are great if you know what  
you are doing, but if you don't know what the feature is and how it  
fits in the JSPWiki architecture, it's not that clear.  HOWTOs and  
tutorials would be great, too.

And, since things are changing between major versions, it's not very  
easy to keep track of all that stuff either.  I know, I still don't  
know all the things that the AAA subsystem is doing - neither can I  
claim to understand the workflow system very well.  I tried to make  
SpamFilter to use it but forgot about it pretty soon, since I could  
never get it to work they way I thought it was supposed to work...

However, I can't stress enough the fact that this is a collaborative  
project, and as such, we *need* more people who can write concise  
documentation, howtos, architecture diagrams, etc.  This beast is too  
big for any single person to ride anymore, so please do help us :-).   
As much as we would like, we can't do *everything*.  Code we can do;  
javadocs we can write; but we would need people who would be willing  
to sort of take the "documentation management" responsibility.   For  
example, see what needs to be documented, and then find volunteers,  
see how much they're willing to do, and then simply divide up the job  
and make sure that people are doing it.

Anybody?

(Yeah, our Javadocs are getting a lot better.  Only 900 missing  
@params to document or something... ;-)

(And don't worry Terry, you aren't saying anything I haven't cursed  
under my breath already...  But though Andrew is right: we *are*  
easier to patch than many other OSS projects.  Though patching them  
is never easy, because we can change everything from under you,  
unless you manage to get the patch approved and into the codebase...)

/Janne

On 7 May 2008, at 19:01, Terry Steichen wrote:

> Andrew,
>
> I hesitated on making the previous 'rant' because I didn't want to  
> come
> off as ungrateful for all the work you, Janne and others have done and
> continue to do.  What I did want to do is expose you perhaps a  
> different
> perspective than you may normally get.  We all are susceptible to the
> COIK fallacy (mentioned below).  When I'm working intensely on my
> project, it all seems pretty clear, obvious and intuitive -  
> although it
> may be completely opaque to others.  I think we all benefit from  
> hearing
> things from a different angle (which doesn't mean, of course, that we
> have to agree with it).
>
> Javadocs and source code comments are certainly better than  
> nothing, and
> I would agree that in the case of JSPWiki, they are better than many.
> However, what I find frustrating is trying to figure out the overall
> strategy of what's going on - the big picture, if you will.  If I use
> JSPWiki in its entirety, with the available look and feel options, the
> standard capabilities of editing pages and providing attachments,  
> things
> go pretty smoothly.  It's when I need to do things differently (or
> implement stuff that isn't available when I need it) that things  
> become
> a bit tougher.  The better I can understand the design philosophy, the
> easier that job is.
>
> Regarding my specific comments, what is your reaction to my concern
> about letting login names be changed?  For many applications, there
> needs to be some consistent thread of identity (for logging, charging,
> analysis, etc) - how is that to be provided if the login name isn't a
> constant?  (The more I think about it, the more I actually think this
> may be a serious problem.)
>
> And I hope I provided enough information on the group changing problem
> for others to verify that it is indeed as I mentioned.  (It works that
> way with both my customized version of JSPWiki and the stock  
> 2.6.2.)  If
> someone else verifies that they see the same thing, then I will add a
> JIRA ticket.
>
> Best,
>
> Terry
>
> On Wed, 2008-05-07 at 11:01 -0400, Andrew Jaquith wrote:
>
>> Terry -- at the risk of making you rant more, I'd simply say the
>> Javadocs are exceptionally detailed, and the source code is well-
>> commented. When in doubt, go to the source.
>>
>> Frankly, I think your expectations a little unrealistic. As somebody
>> who's used a LOT of open source projects, I'd say that our docs (at
>> least the Javadocs, which is really the most important thing for
>> integration) are probably in the top 25% of Java projects I've seen.
>> It beats the crap out of, for example, Jetty and Prefuse (to name two
>> projects I have integrated with lately), but it is not as good as,
>> say, Tomcat or Stripes.
>>
>> I really don't know what to tell you. I'm sorry you find the
>> implementations confusing. I think the other thing you might be
>> missing here is that JSPWiki is now too big for one person to
>> completely comprehend. So, we do the best we can, and we look to
>> volunteers to help out also.
>>
>> Andrew
>>
>> On May 7, 2008, at 10:02 AM, Terry Steichen wrote:
>>
>>> Specific comments inline below.
>>>
>>> <rant - of sorts>
>>> A general comment: It's very hard to figure out how to patch  
>>> JSPWiki,
>>> because it's so hard to figure out precisely how some of the  
>>> functions
>>> are implemented.  For example, I am intrigued by the workflow
>>> capabilities, but haven't a clue as to how to implement them.  Same
>>> for
>>> e-mail factories, negative permissions, e-mail authentication,  
>>> captcha
>>> capabilities, to name a few.  Whenever I've plunged into the JSPWiki
>>> code I've usually come away with being genuinely impressed at the
>>> elegance of the implementation.  But that same elegance also  
>>> makes is
>>> pretty hard to reverse engineer.  (An example of the COIK fallacy -
>>> "Clear Only If Known".) For me, JSPWiki has become a quite  
>>> impressive
>>> set of code (helping me to improve my coding skills, among other
>>> things), providing an impressive set of capabilities, but at the  
>>> same
>>> time becoming an application that's increasingly difficult to
>>> integrate
>>> custom code with (at least in a way that survives the next version
>>> change).
>>> </rant>
>>>
>>> On Tue, 2008-05-06 at 23:26 -0400, Andrew Jaquith wrote:
>>>
>>>> I do know that
>>>> functionally the works as it should: you can change the various  
>>>> names
>>>> in your profile, and ACLs and groups still work. It's worth
>>>> remembering, by the way, that for a long time you could NOT change
>>>> your login name, or wiki name, or full name. Now you can.
>>>
>>> I think we may have become too flexible.  Most systems of which I'm
>>> familiar allow you to change just about any element of a personal
>>> profile EXCEPT the login name.  Not sure why it's desirable for
>>> JSPWiki
>>> to allow such a change (other than we can do it).  Indeed, if we're
>>> logging application-level events, we usually employ the login name
>>> as a
>>> key - but when you allow a person to change that at will, you  
>>> lose the
>>> continuity.
>>>
>>>>
>>>> If you need an ironclad guarantee that only particular things are
>>>> changed (e.g., if the login name hasn't changed, don't change the
>>>> login name), the code in GroupManager.actionPerformed() is what  
>>>> does
>>>> it. We'd gratefully accept a patch if you want it to work  
>>>> differently
>>>> (hint hint).
>>>
>>> A patch would probably be simple, but it seems pointless to  
>>> provide a
>>> patch if we're going to allow the login name to be changed at will.
>>>
>>>>
>>>> This isn't a condition we test for as part of web unit tests, so I
>>>> can't tell if this is anomalous to you or not. If it's easy to
>>>> reproduce, then that would help members (and me) figure out if this
>>>> is
>>>> a bug or just local to your customizations. It would also be useful
>>>> if
>>>> we wanted to make a unit test out of it.
>>>
>>> I have no idea on how to make a standardized test for this  
>>> condition.
>>> However, the problem is easily shown.  When I login and go to  
>>> My_Prefs
>>> and change my Name, if I return to My_prefs, I find that I no longer
>>> have membership in any groups (that I previously belonged to).
>>> However,
>>> after I logout and login again, My_Prefs now shows that the
>>> memberships
>>> are restored (using the new Name).


Mime
View raw message