about javadocs (was: Re: FW: What do we need to release 2.1?)

[Vincent Keunen <vi...@manex.be>]

Thanks Peter, for your message that makes things move forward.  I'm 
adding some comments about the specific item of javadocs.  First, I must 
say that I agree with 2 comments from Noel:

> Internal Documentation
> Absolutely necessary. But NOT to hold up the 2.1 release. We can continue
> to upgrade the web site with new documentation, and any serious developer
> should be working from the CVS


and

> At least get the javadoc complete.
>
> javadocs are for developers. I view 2.1 as a RELEASE build for users. Yes,
> we need to work on the javadocs, but I would not wait for them before
> putting out a stable release build if we can do so.
>
Peter M. Goldstein wrote:

>Internal Documentation
>
>I know some people tend to dismiss internal documentation, but I don't
>see how a project that is seeking to attract developers can function
>without it.  As such I tend to include it in the exit criteria for a
>particular release.
>
>1) All methods and instance variables should be documented.  All classes
>should be documented.  The documentation doesn't need to be extensive,
>but it should be present.  It should include issues such as class/method
>contracts and threading restrictions where appropriate.
>2) All public and protected classes, methods, and variables need to be
>documented using Javadoc style to ensure appropriate Javadoc
>3) The Javadoc should build without warnings
>4) All packages should have package documentation
>
>  
>
Peter, I'd like to modify a bit your suggestion.  From my experience (15 
years of OO software developement), doc should be reduced to the minimum 
(and I find XP discussions about documenting the code quite appropriate 
to modern developments).  Some ideas:

    * code is the only thing that really lives; it changes often
      (writing docs is time consuming and is very difficult to keep in
      sync with the code; and out of sync doc is useless, and may even
      lead you to wrong assumptions...)
    * the code (at the class/method level) should be self explicit: if
      you need doc to explain code, think about rewriting code to make
      it more explicit; also, good developers read code almost as easily
      as the doc (if the code is good, of course)
    * doc is very useful at the package level: "what does this package
      contain, where to look first" (important classes and methods
      should be mentionned)
    * important classes/methods may need some doc
    * important here meaning "part of an API, important for external
      developers" or "part of the basic building blocks of the system,
      that all developers should be comfortable with"

I really don't want to start a lengthy discussion on the pros and cons 
of documentation (see the forum related to that), but I believe that 
docs should not get in the way of developing fast (especially on a 
volunteer basis, with restrained resources).  And I am convinced that it 
won't hurt the project's perennity...

Just my 2 cents (and I hope I did not offense you, Peter).

-- 
!try; do()
--
Vincent Keunen, Ir, http://vincent.keunen.net
Manex, rue Wagner 93, BE-4100 Boncelles, Belgium
Our site: http://www.manex.be

Re: about javadocs (was: Re: FW: What do we need to release 2.1?)

["Andrew C. Oliver" <ac...@apache.org>]

Well said Peter.  If your on Advogoto I'd love to upgrade you.

-Andy

PS... very offtopic
Furthermore de-emphasizing documentation is one of my key beefs with XP.
While I hate 300 page specs, I hate 0 page ones too.

Peter M. Goldstein wrote:
> Vincent,
> 
> I'm not offended, although I disagree almost entirely with your points.
> :)
> 
> Basically I feel that on distributed, volunteer projects extensive and
> appropriate documentation is even more important than on projects being
> done by a full-time, localized development team.  And I feel that it is
> extremely important even in the latter case.
> 
> While XP is an interesting methodology, James is in no way an XP
> project.  We are using none of the XP techniques (pair programming,
> rapid rotation of developers to different parts of the code base,
> aggressive refactoring of unclear code etc.) that make internal
> documentation far less important.  And as observation of the changelog
> indicates, leaving javadoc out vs. adding javadoc has not made the
> development any faster.
> 
> I believe that one of the essential things an open source project must
> do is attract developers.  You do that by making the projects
> interesting, and the code easy to understand.  To me, that means
> internal documentation.  That's what allows a new developer to come up
> to speed in a very short time and participate productively in the
> project.  And on this point at least the Apache code standards seem to
> agree with me.  :)
> 
> I also suggested that the internal documentation be tied to a release
> because:
> 
> i) That way it actually gets done
> ii) When the release announcement spurs a few developers to take a look
> at the code base, they'll find a well-documented, inviting code base.
> 
> I'd be happy to continue this discussion offline, but I stand by my
> original wish list entry.  
> 
> --Peter
> 
> 
>>-----Original Message-----
>>From: Vincent Keunen [mailto:vincent.keunen@manex.be]
>>Sent: Sunday, August 18, 2002 7:13 AM
>>To: James Developers List
>>Subject: about javadocs (was: Re: FW: What do we need to release 2.1?)
>>
>>Thanks Peter, for your message that makes things move forward.  I'm
>>adding some comments about the specific item of javadocs.  First, I
> 
> must
> 
>>say that I agree with 2 comments from Noel:
>>
>>
>>>Internal Documentation
>>>Absolutely necessary. But NOT to hold up the 2.1 release. We can
>>
>>continue
>>
>>>to upgrade the web site with new documentation, and any serious
>>
>>developer
>>
>>>should be working from the CVS
>>
>>
>>and
>>
>>
>>>At least get the javadoc complete.
>>>
>>>javadocs are for developers. I view 2.1 as a RELEASE build for
>>
> users.
> 
>>Yes,
>>
>>>we need to work on the javadocs, but I would not wait for them
>>
> before
> 
>>>putting out a stable release build if we can do so.
>>>
>>
>>Peter M. Goldstein wrote:
>>
>>
>>>Internal Documentation
>>>
>>>I know some people tend to dismiss internal documentation, but I
>>
> don't
> 
>>>see how a project that is seeking to attract developers can function
>>>without it.  As such I tend to include it in the exit criteria for a
>>>particular release.
>>>
>>>1) All methods and instance variables should be documented.  All
>>
> classes
> 
>>>should be documented.  The documentation doesn't need to be
>>
> extensive,
> 
>>>but it should be present.  It should include issues such as
>>
> class/method
> 
>>>contracts and threading restrictions where appropriate.
>>>2) All public and protected classes, methods, and variables need to
>>
> be
> 
>>>documented using Javadoc style to ensure appropriate Javadoc
>>>3) The Javadoc should build without warnings
>>>4) All packages should have package documentation
>>>
>>>
>>>
>>
>>Peter, I'd like to modify a bit your suggestion.  From my experience
> 
> (15
> 
>>years of OO software developement), doc should be reduced to the
> 
> minimum
> 
>>(and I find XP discussions about documenting the code quite
> 
> appropriate
> 
>>to modern developments).  Some ideas:
>>
>>    * code is the only thing that really lives; it changes often
>>      (writing docs is time consuming and is very difficult to keep in
>>      sync with the code; and out of sync doc is useless, and may even
>>      lead you to wrong assumptions...)
>>    * the code (at the class/method level) should be self explicit: if
>>      you need doc to explain code, think about rewriting code to make
>>      it more explicit; also, good developers read code almost as
> 
> easily
> 
>>      as the doc (if the code is good, of course)
>>    * doc is very useful at the package level: "what does this package
>>      contain, where to look first" (important classes and methods
>>      should be mentionned)
>>    * important classes/methods may need some doc
>>    * important here meaning "part of an API, important for external
>>      developers" or "part of the basic building blocks of the system,
>>      that all developers should be comfortable with"
>>
>>I really don't want to start a lengthy discussion on the pros and cons
>>of documentation (see the forum related to that), but I believe that
>>docs should not get in the way of developing fast (especially on a
>>volunteer basis, with restrained resources).  And I am convinced that
> 
> it
> 
>>won't hurt the project's perennity...
>>
>>Just my 2 cents (and I hope I did not offense you, Peter).
>>
>>--
>>!try; do()
>>--
>>Vincent Keunen, Ir, http://vincent.keunen.net
>>Manex, rue Wagner 93, BE-4100 Boncelles, Belgium
>>Our site: http://www.manex.be
> 





--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: about javadocs (was: Re: FW: What do we need to release 2.1?)

[Tetsuya Kitahata <te...@nifty.ne.jp>]

Hi, Andy and all.

On Sun, 18 Aug 2002 23:21:42 -0400
"Andrew C. Oliver" <ac...@apache.org> wrote:

> To be honest Tetsuya, it makes me scared to use it.  Javadoc to me is so 
> basic and takes so little time, to actually argue against it...  To me 
> this is the same as an argument to write variables a1, a2, a3... Its 
> code quality.  This is an active argument for poor code quality and I 
> can't believe this is controversial!

I know your feelings, but it seems that it is the difference of 
"where and when to put our milestones" things.
For example, "our objectives at version 2.1 are not necessary 
complete javadocs, but at version 3.0, complete javadocs are
necessary" ... I think (for example) this is possible.

--

I agreed with Noel's opinion, "But javadocs for developers is not a 
reason to hold end users hostage", because this matter also applies
to the translation.
To catch up with frequently changed javadocs (to keep in sync) is
very difficult and almost impossible things.
The difference between this two Japanese Translation Groups(?)
http://www.terra-intl.com/jakarta/
http://www.ingrid.org/jajakarta/
is apparent. I (the former one) clearly declared " I will not
translate Javadocs because external documents are very important
for the PROMOTION of jakarta-projects but javadocs are different."
That's why I can speed it up to translate 9 jakarta-projects (including
JAMES) and the latter could not, it seems.

That's why I love the Noel's sentence.

Regards,

-- Tetsuya Kitahata <ki...@bb.mbn.or.jp>



--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: about javadocs (was: Re: FW: What do we need to release 2.1?)

[Serge Knystautas <se...@lokitech.com>]

Andrew,

If you feel there's something glaringly wrong that should be improved,
patches are always greatly welcome.

For my money, the only thing that should hold up a release is a volunteer
saying they will fix something but won't have it ready until date X.  Beyond
that, changelogs go out with all the contributors and committers names on
them... believe me, they're not looking to put out a bad product and just
are trying to find a balance.

Serge Knystautas
Loki Technologies
http://www.lokitech.com/
----- Original Message -----
From: "Andrew C. Oliver" <ac...@apache.org>
Newsgroups: gmane.comp.jakarta.james.devel
To: <ja...@jakarta.apache.org>
Sent: Sunday, August 18, 2002 11:21 PM
Subject: Re: about javadocs (was: Re: FW: What do we need to release 2.1?)


> To be honest Tetsuya, it makes me scared to use it.  Javadoc to me is so
> basic and takes so little time, to actually argue against it...  To me
> this is the same as an argument to write variables a1, a2, a3... Its
> code quality.  This is an active argument for poor code quality and I
> can't believe this is controversial!
>
> Tetsuya Kitahata wrote:
> > On Sun, 18 Aug 2002 20:40:35 -0400
> > "Noel J. Bergman" <no...@devtech.com> wrote:
> >
> >
> >>Everyone is agreeing that the documentation is necessary.  But javadocs
for
> >>developers is not a reason to hold end users hostage.
> >
> >
> > I love this sentence, "But javadocs for developers is not a reason to
> > hold end users hostage".
> >
> > I think documentation is VERY important, however, in my position
> > just exernal documents (for users) not necessarily internal ones
> > (javadocs).
> >
> > Sorry for the interruption.
> >
> > -- Tetsuya Kitahata <ki...@bb.mbn.or.jp>



--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: about javadocs (was: Re: FW: What do we need to release 2.1?)

["Andrew C. Oliver" <ac...@apache.org>]

To be honest Tetsuya, it makes me scared to use it.  Javadoc to me is so 
basic and takes so little time, to actually argue against it...  To me 
this is the same as an argument to write variables a1, a2, a3... Its 
code quality.  This is an active argument for poor code quality and I 
can't believe this is controversial!

Tetsuya Kitahata wrote:
> On Sun, 18 Aug 2002 20:40:35 -0400
> "Noel J. Bergman" <no...@devtech.com> wrote:
> 
> 
>>Everyone is agreeing that the documentation is necessary.  But javadocs for
>>developers is not a reason to hold end users hostage.
> 
> 
> I love this sentence, "But javadocs for developers is not a reason to
> hold end users hostage".
> 
> I think documentation is VERY important, however, in my position
> just exernal documents (for users) not necessarily internal ones
> (javadocs).
> 
> Sorry for the interruption.
> 
> -- Tetsuya Kitahata <ki...@bb.mbn.or.jp>





--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: about javadocs (was: Re: FW: What do we need to release 2.1?)

[Tetsuya Kitahata <te...@nifty.ne.jp>]

On Sun, 18 Aug 2002 20:40:35 -0400
"Noel J. Bergman" <no...@devtech.com> wrote:

> Everyone is agreeing that the documentation is necessary.  But javadocs for
> developers is not a reason to hold end users hostage.

I love this sentence, "But javadocs for developers is not a reason to
hold end users hostage".

I think documentation is VERY important, however, in my position
just exernal documents (for users) not necessarily internal ones
(javadocs).

Sorry for the interruption.

-- Tetsuya Kitahata <ki...@bb.mbn.or.jp>


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: Jakarta James Nightly Build

[Stephen McConnell <mc...@apache.org>]

Paul Hammant wrote:

> Stephen,
>
>>> To more knowledgeable heads than I,
>>>
>>> Noel and I have been looking at the nightly build process and are a
>>> little disturbed by the fact that:
>>>
>>> i) It is failing
>>> ii) It is failing without notifying james-dev
>>>
>>
>> This explains a lot.  With no notification of failures, the Avalon 
>> Community have been moving along in ignorant bliss (relative to the 
>> James Commnity).  Over the last few days that has been discussion 
>> concerning inconsitencies in Cornerstone jar brough about by some 
>> recent testing I've been doing of James using the Avalon CVS builds 
>> of Cornerstone. With gump working we would have spotted the issue 
>> months ago.
>>
>> Getting this back in place would be really good becuse you can 
>> validate that the Avalon Community are not braking anything as a 
>> result of maintainance and service development.
>
>
> Err not true dude.  The problem exists because casting (I think) which 
> neither gump nor a guy doing 'ant clean, ant dist' can test for.  


I stand corrected!  A pure Gump run will only pick up compile time issues.
However, a unit test on someting link the SMTP server will catch this 
sort of issue.  Aside from that - getting in some unit tests on 
individual Cornersone components could be highly valuable - I have a 
sneaking suspision that the errors I'm seeing in the James runtime 
testing are unrelated to James code and actually concern the file 
persistence in the cornerston/store package - but its unconfirmed at 
this stage.

Cheers, Steve.

>
>>> See the nightly build report here:
>>>
>>> http://jakarta.apache.org/builds/gump/latest/jakarta-james.html
>>>
>>> After examining the definition file here,
>>>
>>> http://jakarta.apache.org/builds/gump/latest/module_jakarta-james.html
>>>
>>> it is very clear that this definition is pretty far out of date.  Among
>>> other things, the file refers to a James.bar, which if I recall
>>> correctly was the predecessor to the current James.sar.  So the file
>>> needs to be updated.
>>>
>>
>> Pete the right person to talk to - he knows this stuff inside out.
>
>
> Indeed he is.  Confuses the hell out me me.
>
> - Paul
>
>
> -- 
> To unsubscribe, e-mail:   
> <ma...@jakarta.apache.org>
> For additional commands, e-mail: 
> <ma...@jakarta.apache.org>
>

-- 

Stephen J. McConnell

OSM SARL
digital products for a global economy
mailto:mcconnell@osm.net
http://www.osm.net




--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: Jakarta James Nightly Build

[Paul Hammant <Pa...@yahoo.com>]

Stephen,

>> To more knowledgeable heads than I,
>>
>> Noel and I have been looking at the nightly build process and are a
>> little disturbed by the fact that:
>>
>> i) It is failing
>> ii) It is failing without notifying james-dev
>>
>
> This explains a lot.  With no notification of failures, the Avalon 
> Community have been moving along in ignorant bliss (relative to the 
> James Commnity).  Over the last few days that has been discussion 
> concerning inconsitencies in Cornerstone jar brough about by some 
> recent testing I've been doing of James using the Avalon CVS builds of 
> Cornerstone. With gump working we would have spotted the issue months ago.
>
> Getting this back in place would be really good becuse you can 
> validate that the Avalon Community are not braking anything as a 
> result of maintainance and service development.

Err not true dude.  The problem exists because casting (I think) which 
neither gump nor a guy doing 'ant clean, ant dist' can test for.  

>> See the nightly build report here:
>>
>> http://jakarta.apache.org/builds/gump/latest/jakarta-james.html
>>
>> After examining the definition file here,
>>
>> http://jakarta.apache.org/builds/gump/latest/module_jakarta-james.html
>>
>> it is very clear that this definition is pretty far out of date.  Among
>> other things, the file refers to a James.bar, which if I recall
>> correctly was the predecessor to the current James.sar.  So the file
>> needs to be updated.
>>
>
> Pete the right person to talk to - he knows this stuff inside out.

Indeed he is.  Confuses the hell out me me.

- Paul


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: Jakarta James Nightly Build

[Danny Angus <da...@apache.org>]

I wrote,
> >But the point of Gump is that it tests the domain level build by building
> >every part of the domain from scratch.
Steve replied,
> Which from my point of view is the really valuble thing

Mine too, as a newcomer to the ideas of domain engineering I can totally
subscribe to the principles of Gump, and seeing Avalon as a provider of
domain commonalities, and James as an expression of variability, I can see
how the domain level build testing of Gump would help accelerate the
handling of James/Avalon issues.

I'm not sure what to do about Gump/James, but I do know where to start
poking around..

d.


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: Jakarta James Nightly Build

[Stephen McConnell <mc...@apache.org>]

Danny Angus wrote:

>>Again, personally, I would not want James to build against the Phoenix
>>nightly builds.  I'd prefer that it build against the snapshot
>>that is part
>>of James.
>>    
>>
>
>But the point of Gump is that it tests the domain level build by building
>every part of the domain from scratch.
>  
>

Which from my point of view is the really valuble thing - validation the 
Avalon Framework, Excalibur Xxxx, Cornerstone component Xxxx, Phoenix, 
etc. are all in sync - and delivering what your expecting.  It goes a 
long way in providing the James community much more specific information 
about a problem - information that is sufficient for the Avalon 
community to react appropriately if a problem does occur.  If the same 
thing were put in place with Cocoon the we (Avalon Land) would have a 
rather nice early warning process in place.

Cheers, Steve.


>d.
>
>
>--
>To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
>For additional commands, e-mail: <ma...@jakarta.apache.org>
>
>  
>

-- 

Stephen J. McConnell

OSM SARL
digital products for a global economy
mailto:mcconnell@osm.net
http://www.osm.net




--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: Jakarta James Nightly Build

["Noel J. Bergman" <no...@devtech.com>]

> But thats the point isn't it? Gump isn't just there to make nightly
builds.

That isn't what I understood previously, so this is enlightening.  :-)

> Of course if you'd asked on the list you could have been told. :-)

I refer you to the start of this thread: a message was posted to the list
saying that we had noticed that the Nighly Builds weren't working, and
asking questions.  And answers have been posted.

	--- Noel


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: Jakarta James Nightly Build

[Danny Angus <da...@apache.org>]

> Fair enough.  I would not have gotten that from the description of Nightly
> Build.

But thats the point isn't it? Gump isn't just there to make nightly builds.

> This comfirms what I said to Peter

What did you say to Peter? *please* don't refer, in an offhand way, to
conversations we haven't all been privy to.

> about how I thought the earlier builds
> had been done.  You did them on a clean machine, and posted them back up.

Of course if you'd asked on the list you could have been told. :-)

d.


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: Jakarta James Nightly Build

["Noel J. Bergman" <no...@devtech.com>]

> the premis of Gump, as I understand it, that it encourages
> continuous integration within the jakarta domain.

Fair enough.  I would not have gotten that from the description of Nightly
Build.

> Its certainly reasonable to suggest a self-contained nightly build of
James,
> the problem is resources, the apache machines ('cept nagoya) run BSD so we
> can't build on them, therefore someone needs to donate the build location.

Thanks for explaining this, Danny.  :-)

> I changed build.xml to put the downloads into a directory that can be
scp'ed
> across by a single command to make automatic releases easier, and I have a
> "clean" machine that I build releases on ...

This comfirms what I said to Peter about how I thought the earlier builds
had been done.  You did them on a clean machine, and posted them back up.
(a) thanks, (b) how can anyone help?

	--- Noel


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: Jakarta James Nightly Build

[Danny Angus <da...@apache.org>]

Noel wrote,

> > But the point of Gump is that it tests the domain level build
> by building
> > every part of the domain from scratch.
>
> That assumes that the domain is evolving in synch, and is intended to be
> released in synch.  It works great for a domain level project, but that's
> not necessarily the case.

No, but it is the premis of Gump, as I understand it, that it encourages
continuous integration within the jakarta domain.

<snipped dull comment from self/>

> From that perspective, I could see two nightly builds: a domain
> level build,
> and the other a build of James against the components that it is
> intended to
> work with.

Its certainly reasonable to suggest a self-contained nightly build of James,
the problem is resources, the apache machines ('cept nagoya) run BSD so we
can't build on them, therefore someone needs to donate the build location.

I changed build.xml to put the downloads into a directory that can be scp'ed
across by a single command to make automatic releases easier, and I have a
"clean" machine that I build releases on, but I wouldn't like James to rely
on it, as its continued presence is outwith my control.
I would also be wary of entrusting my apache password or keys to a machine
on which there are other people with root.

Hence the reason I instigated the "latest" directory, to make builds
available at random when it seems worthwhile, and that aren't deleted by
someones cron job.
Anyone is welcome to cajole us into putting a new version in latest.

d.


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: Jakarta James Nightly Build

["Noel J. Bergman" <no...@devtech.com>]

> But the point of Gump is that it tests the domain level build by building
> every part of the domain from scratch.

That assumes that the domain is evolving in synch, and is intended to be
released in synch.  It works great for a domain level project, but that's
not necessarily the case.

> a newcomer to the ideas of domain engineering I can totally
> subscribe to the principles of Gump, and seeing Avalon as a
> provider of domain commonalities, and James as an expression
> of variability, I can see how the domain level build testing
> of Gump would help accelerate the handling of James/Avalon issues.

>From that perspective, I could see two nightly builds: a domain level build,
and the other a build of James against the components that it is intended to
work with.

At some point a project with dependencies needs to freeze the dependencies.
You can't just take their latest CVS.

	--- Noel


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: Jakarta James Nightly Build

[Danny Angus <da...@apache.org>]

> Again, personally, I would not want James to build against the Phoenix
> nightly builds.  I'd prefer that it build against the snapshot
> that is part
> of James.

But the point of Gump is that it tests the domain level build by building
every part of the domain from scratch.

d.


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: Jakarta James Nightly Build

["Noel J. Bergman" <no...@devtech.com>]

> This explains a lot.  With no notification of failures, the Avalon
> Community have been moving along in ignorant bliss (relative to the
> James Commnity).

There are Avalon developers here on this mailing list aware of what is going
on.  Some months ago, Paul Hammant kindly offered to keep James going well
with Phoenix, and to be responsible for changing the James infrastructure to
match changes in Phoenix; he was made a James committer for this purpose.
James has its own snapshot of Phoenix, allowing James and Phoenix to evolve
at their own pace.

Apparently, there was a decision made half a year ago to eliminate the
Component interface in favor of A-Better-Way.  Because of some ... shall we
say "anemia" ... in the Mailet v1 API, there are Mailets that must get at
non-Mailet API functionality.  They do that by requesting the
ComponentManager via MailetContext.getAttribute(), and going on from there.
It is not a problem to migrate the James code, but Paul has expressed
concern about third-party mailets (outside of the scope of the CVS).

My proposal is that Paul remove dependency upon the Component interface
within Jame's code, and support foreign matchers/mailets as follows.  The
only documented way for a matcher/mailet to get the component manager is via
a specific mechanism, and the set of components is limited.  We can provide
our own Component code that lies (and wraps) as necessary, until we can drop
that code entirely.  James' stock matchers/mailets would show how to make
the transition.

Personally, I have no problem with Phoenix continuing to evolve, given that
they've accepted responsibility for converting James along.

Again, personally, I would not want James to build against the Phoenix
nightly builds.  I'd prefer that it build against the snapshot that is part
of James.

	--- Noel


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: Jakarta James Nightly Build

[Stephen McConnell <mc...@apache.org>]

Peter M. Goldstein wrote:

>To more knowledgeable heads than I,
>
>Noel and I have been looking at the nightly build process and are a
>little disturbed by the fact that:
>
>i) It is failing
>ii) It is failing without notifying james-dev
>

This explains a lot.  With no notification of failures, the Avalon 
Community have been moving along in ignorant bliss (relative to the 
James Commnity).  Over the last few days that has been discussion 
concerning inconsitencies in Cornerstone jar brough about by some recent 
testing I've been doing of James using the Avalon CVS builds of 
Cornerstone. With gump working we would have spotted the issue months ago.

Getting this back in place would be really good becuse you can validate 
that the Avalon Community are not braking anything as a result of 
maintainance and service development.

>
>
>See the nightly build report here:
>
>http://jakarta.apache.org/builds/gump/latest/jakarta-james.html
>
>After examining the definition file here,
>
>http://jakarta.apache.org/builds/gump/latest/module_jakarta-james.html
>
>it is very clear that this definition is pretty far out of date.  Among
>other things, the file refers to a James.bar, which if I recall
>correctly was the predecessor to the current James.sar.  So the file
>needs to be updated.
>

Its also out-of-date relative some restructuring that took place of the 
Excalibur project.

>
>The build is currently failing because of unnecessary dependencies -
>James builds off snapshots of the assorted Avalon subprojects and hence
>does not need those project builds to succeed.  So the dependency
>entries need to be updated.
>
>I'm willing to volunteer to do the jakarta-james.xml file update.  My
>big problem is that I don't know where the file is, and I don't think I
>have write-access to it.  I'd like to get one of the Apache elders to
>give me a hand with this.  As Peter Donald is listed in the nag tag, I'm
>cc'ing him on this email.  Any help would be greatly appreciated.
>

Pete the right person to talk to - he knows this stuff inside out.

Cheers, Steve.


-- 

Stephen J. McConnell

OSM SARL
digital products for a global economy
mailto:mcconnell@osm.net
http://www.osm.net




--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: Jakarta James Nightly Build

[Peter Donald <pe...@apache.org>]

The gump descriptors are part of Gump which is a proposal in the Alexandria 
project. You can locate the descriptor by looking in cvs at

jakarta-alexandria/proposal/gump/projects/jakarta-james.xml

And send questions, diffs and patches to alexandria-dev@jakarta.apache.org 
mailing list.

On Mon, 19 Aug 2002 11:45, Peter M. Goldstein wrote:
> To more knowledgeable heads than I,
>
> Noel and I have been looking at the nightly build process and are a
> little disturbed by the fact that:
>
> i) It is failing
> ii) It is failing without notifying james-dev
>
> See the nightly build report here:
>
> http://jakarta.apache.org/builds/gump/latest/jakarta-james.html
>
> After examining the definition file here,
>
> http://jakarta.apache.org/builds/gump/latest/module_jakarta-james.html
>
> it is very clear that this definition is pretty far out of date.  Among
> other things, the file refers to a James.bar, which if I recall
> correctly was the predecessor to the current James.sar.  So the file
> needs to be updated.
>
> The build is currently failing because of unnecessary dependencies -
> James builds off snapshots of the assorted Avalon subprojects and hence
> does not need those project builds to succeed.  So the dependency
> entries need to be updated.
>
> I'm willing to volunteer to do the jakarta-james.xml file update.  My
> big problem is that I don't know where the file is, and I don't think I
> have write-access to it.  I'd like to get one of the Apache elders to
> give me a hand with this.  As Peter Donald is listed in the nag tag, I'm
> cc'ing him on this email.  Any help would be greatly appreciated.
>
> --Peter

-- 
Cheers,

Peter Donald
--------------------------------------------------
 Logic: The art of being wrong with confidence...
--------------------------------------------------


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: Jakarta James Nightly Build

[Paul Hammant <Pa...@yahoo.com>]

Peter,

>To more knowledgeable heads than I,
>
>Noel and I have been looking at the nightly build process and are a
>little disturbed by the fact that:
>
>i) It is failing
>ii) It is failing without notifying james-dev
>
>See the nightly build report here:
>
>http://jakarta.apache.org/builds/gump/latest/jakarta-james.html
>
>After examining the definition file here,
>
>http://jakarta.apache.org/builds/gump/latest/module_jakarta-james.html
>
>it is very clear that this definition is pretty far out of date.  Among
>other things, the file refers to a James.bar, which if I recall
>correctly was the predecessor to the current James.sar.  So the file
>needs to be updated.
>
No, the bar (block archive) was simply replaced with jar.  bars (now 
jars) sit inside sars.

>The build is currently failing because of unnecessary dependencies -
>James builds off snapshots of the assorted Avalon subprojects and hence
>does not need those project builds to succeed.  So the dependency
>entries need to be updated.
>
>I'm willing to volunteer to do the jakarta-james.xml file update.  My
>big problem is that I don't know where the file is, and I don't think I
>have write-access to it.  I'd like to get one of the Apache elders to
>give me a hand with this.  As Peter Donald is listed in the nag tag, I'm
>cc'ing him on this email.  Any help would be greatly appreciated.
>

jakarta-alexandria/proposal/gump/project/jakarta-james.xml I think.

- Paul


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: Jakarta James Nightly Build

[Stephen McConnell <mc...@apache.org>]

Danny Angus wrote:

>the problem is that Avalon isn't building, in particular
>http://jakarta.apache.org/builds/gump/latest/jakarta-avalon-excalibur.html
>  
>

Generalization isn't a good thing!
James has depedencies on a set of the Excalibur projects - not all of 
Excalibur.  What is needed is that the James gumjp description is 
specific about the paricular Excalibur projects that James requires. 
 After all - Exalibur contains a lot of things that vary from new, 
exciting and alpha, through to dull boring and stable.

Cheers, Steve.

-- 

Stephen J. McConnell

OSM SARL
digital products for a global economy
mailto:mcconnell@osm.net
http://www.osm.net




--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: Jakarta James Nightly Build

[Danny Angus <da...@apache.org>]

the problem is that Avalon isn't building, in particular
http://jakarta.apache.org/builds/gump/latest/jakarta-avalon-excalibur.html


> it is very clear that this definition is pretty far out of date.  Among
> other things, the file refers to a James.bar, which if I recall
> correctly was the predecessor to the current James.sar.  So the file
> needs to be updated.


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Jakarta James Nightly Build

["Peter M. Goldstein" <pe...@yahoo.com>]

To more knowledgeable heads than I,

Noel and I have been looking at the nightly build process and are a
little disturbed by the fact that:

i) It is failing
ii) It is failing without notifying james-dev

See the nightly build report here:

http://jakarta.apache.org/builds/gump/latest/jakarta-james.html

After examining the definition file here,

http://jakarta.apache.org/builds/gump/latest/module_jakarta-james.html

it is very clear that this definition is pretty far out of date.  Among
other things, the file refers to a James.bar, which if I recall
correctly was the predecessor to the current James.sar.  So the file
needs to be updated.

The build is currently failing because of unnecessary dependencies -
James builds off snapshots of the assorted Avalon subprojects and hence
does not need those project builds to succeed.  So the dependency
entries need to be updated.

I'm willing to volunteer to do the jakarta-james.xml file update.  My
big problem is that I don't know where the file is, and I don't think I
have write-access to it.  I'd like to get one of the Apache elders to
give me a hand with this.  As Peter Donald is listed in the nag tag, I'm
cc'ing him on this email.  Any help would be greatly appreciated.

--Peter




--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: about javadocs (was: Re: FW: What do we need to release 2.1?)

["Noel J. Bergman" <no...@devtech.com>]

Vincent Keunen wrote:
> > First, I must say that I agree with 2 comments from Noel:
> > > Internal Documentation
> > > Absolutely necessary. But NOT to hold up the 2.1 release. We can
continue
> > > to upgrade the web site with new documentation, and any serious
developer
> > > should be working from the CVS
> You wouldn't release Documentation with no code would you?
> Why would you release code with no documentation?  If documentation
> isn't a condition for release, you'll never do it.

Everyone is agreeing that the documentation is necessary.  But javadocs for
developers is not a reason to hold end users hostage.  The psychology is
backwards.  The documentation is getting done, but telling developers who
can get the current code from the CVS that there won't be a user release
until there is developer documentation is not going to incent them to do
javadocs.  If they don't care, they don't care, and they aren't the ones
being held hostage by this false incentive.  Fortunately, Peter has both
time and interest, and he is doing a great job of updating the internal
documentation.

>> javadocs are for developers. I view 2.1 as a RELEASE build for users.
>> Yes, we need to work on the javadocs, but I would not wait for them
>> before putting out a stable release build if we can do so.

> retranslate:  "Code quality is not important"

Overly simplistic software cliche.  2.1 is superior in all ways to 2.0a3,
including javadocs (albiet incomplete).

Ironically, I just answered a question from someone who downloaded 2.0a3
over a week ago, and ran into the erroneous end user documentation.
Releasing 2.1, which has CORRECT documentation would have saved that person
10 days of grief.  Sure, it would have saved me the 30 seconds it took to
reply, but it would have saved him 10 days.

At the least, I do not see any reason not to replace 2.1a1 with a 2.1a2
Milestone Build based upon what we have now, and invite end users to help
out with the user documentation.  The CVS HEAD currently fills all the
criteria necessary for a Milestone Build.

	--- Noel


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: about javadocs (was: Re: FW: What do we need to release 2.1?)

["Andrew C. Oliver" <ac...@apache.org>]

Vincent Keunen wrote:
> Thanks Peter, for your message that makes things move forward.  I'm 
> adding some comments about the specific item of javadocs.  First, I must 
> say that I agree with 2 comments from Noel:
> 
>> Internal Documentation
>> Absolutely necessary. But NOT to hold up the 2.1 release. We can continue
>> to upgrade the web site with new documentation, and any serious developer
>> should be working from the CVS
>

I disagree. You wouldn't release Documentation with no code would you? 
Why would you release code with no documentation?  If documentation 
isn't a condition for release, you'll never do it.  So say what you mean
"Absolutely someone else...the mythical someone else..should document 
JAMES, but quality is not important to me so I'd rather get it out the 
door undocumented and hope the mythical someone else comes along"

> 
>> javadocs are for developers. I view 2.1 as a RELEASE build for users. 
>> Yes,
>> we need to work on the javadocs, but I would not wait for them before
>> putting out a stable release build if we can do so.
>>

retranslate:  "Code quality is not important"


> Peter M. Goldstein wrote:
> 
>> Internal Documentation
>>
>> I know some people tend to dismiss internal documentation, but I don't
>> see how a project that is seeking to attract developers can function
>> without it.  As such I tend to include it in the exit criteria for a
>> particular release.
>>
>> 1) All methods and instance variables should be documented.  All classes
>> should be documented.  The documentation doesn't need to be extensive,
>> but it should be present.  It should include issues such as class/method
>> contracts and threading restrictions where appropriate.
>> 2) All public and protected classes, methods, and variables need to be
>> documented using Javadoc style to ensure appropriate Javadoc
>> 3) The Javadoc should build without warnings
>> 4) All packages should have package documentation
>>
>>  
>>
> Peter, I'd like to modify a bit your suggestion.  From my experience (15 
> years of OO software developement), doc should be reduced to the minimum 
> (and I find XP discussions about documenting the code quite appropriate 
> to modern developments).  Some ideas:
> 
>    * code is the only thing that really lives; it changes often
>      (writing docs is time consuming and is very difficult to keep in
>      sync with the code; and out of sync doc is useless, and may even
>      lead you to wrong assumptions...)
>    * the code (at the class/method level) should be self explicit: if
>      you need doc to explain code, think about rewriting code to make
>      it more explicit; also, good developers read code almost as easily
>      as the doc (if the code is good, of course)
>    * doc is very useful at the package level: "what does this package
>      contain, where to look first" (important classes and methods
>      should be mentionned)
>    * important classes/methods may need some doc
>    * important here meaning "part of an API, important for external
>      developers" or "part of the basic building blocks of the system,
>      that all developers should be comfortable with"
> 
> I really don't want to start a lengthy discussion on the pros and cons 
> of documentation (see the forum related to that), but I believe that 
> docs should not get in the way of developing fast (especially on a 
> volunteer basis, with restrained resources).  And I am convinced that it 
> won't hurt the project's perennity...
> 
> Just my 2 cents (and I hope I did not offense you, Peter).
> 





--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: about javadocs (was: Re: FW: What do we need to release 2.1?)

["Noel J. Bergman" <no...@devtech.com>]

> how long did it take you to find a class to use as an example, 
> or did you just go down the left nav in alphabetical order?

About 30 seconds.  I just picked at random from the nav bar.

> some of the committers of POI would like a policy of
> requiring a unit test per class before release!

A good idea.  Something that we all ought to be doing.

> I'll NEVER understand your position that javadoc isn't
> important enough to hold up a formal release.

Fact: 2.0a3 is listed as a Release Build.
Fact: 2.1a1 improves upon 2.0a3.

View: IF it is as/more stable, it should replace its predecessor.

	--- Noel



--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: about javadocs (was: Re: FW: What do we need to release 2.1?)

["Andrew C. Oliver" <ac...@apache.org>]

> James' code isn't undocumented, but there are various uncommented members,
> so Peter is trying to complete the documentation.  The same can be said of
> org.apache.poi.  For example, AbstractFunctionPtg is missing javadocs for a
> number of members.

I'll bite...

While this is a tad offtopic...

<soap-box>

For one, some of the members are deliberately uncommented (I don't do
inherited members as the javadoc will override the parent's).

However, POI will not have a release with formulas enabled by default 
until its fixed.  It will have "development builds" (alphas or 
"milestones") until then, but thats it.  Why: its not of release 
quality.  As evidence, formula support is still in early beta.

So Noel, how long did it take you to find a class to use as an example, 
or did you just go down the left nav in alphabetical order? That one is 
a few layers deep and in the most beta of code!  I'm impressed at your 
resolve!  If you can find others I'll make a list of them and make sure 
I catch them all before +1'ing our next release.

To take THAT a step further, some of the committers of POI would like a 
policy of requiring a unit test per class before release!  That will 
likely pass for our 3.0 release.  We'll probably need a few enhancements 
to Centipede to support "test-first" a little better before we draft that.

Just FYI, the policy on this is covered here: 
http://jakarta.apache.org/poi/resolutions/res001.html

and more or less here:

http://jakarta.apache.org/site/source.html

Its a quality thing.

</soapbox>

Anyhow, I'm just a guy trying to make hide or hair of james.  My opinion 
shouldn't count for much, but I'll NEVER understand your position that 
javadoc isn't important enough to hold up a formal release.  (I already 
said milestone and dev releases are reasonable, but I don't think YOU 
gave it a close read)

Thanks,

Andy




--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: about javadocs (was: Re: FW: What do we need to release 2.1?)

["Andrew C. Oliver" <ac...@apache.org>]

I will write Javadocs as I come to understand what the heck things are
(this is of course is a chicken and the egg proposition).

My interest is more in creating an M$ Exchange protocol replacement. 
But its a ways out and first IMAP needs to get up to snuff.

-Andy

Tetsuya Kitahata wrote:
> On Mon, 19 Aug 2002 00:46:55 -0400
> "Noel J. Bergman" <no...@devtech.com> wrote:
> 
> 
>>And, of course, this has nothing to do with end user documentation,
>>such as telling a user how to install and deploy James.  You know,
>>little things like how to setup a mailing list (have fun reading the
>>docs and FAQ), how different matchers and mailets interact with each
>>other, or something as fundamental as the correct documentation for
>>how to setup a database URL (which is correct in the CVS, and wrong in
>> the current download).
> 
> 
> I agree with this. James' user documents are very good and smart.
> I think just Andy want to commit some Mailets as a developer, or
> seek where to.
> 
> I'm wondering how nice it would be to add Mailet which automatically
> collect the attached MS-Office files in e-mails and produce
> automatically RDF/XMLs of these files ... for example.
> (This is why I have come to be interested in POI and James)
> 
> -- Tetsuya Kitahata <ki...@bb.mbn.or.jp>





--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: about javadocs (was: Re: FW: What do we need to release 2.1?)

[Tetsuya Kitahata <te...@nifty.ne.jp>]

On Mon, 19 Aug 2002 00:46:55 -0400
"Noel J. Bergman" <no...@devtech.com> wrote:

> And, of course, this has nothing to do with end user documentation,
> such as telling a user how to install and deploy James.  You know,
> little things like how to setup a mailing list (have fun reading the
> docs and FAQ), how different matchers and mailets interact with each
> other, or something as fundamental as the correct documentation for
> how to setup a database URL (which is correct in the CVS, and wrong in
>  the current download).

I agree with this. James' user documents are very good and smart.
I think just Andy want to commit some Mailets as a developer, or
seek where to.

I'm wondering how nice it would be to add Mailet which automatically
collect the attached MS-Office files in e-mails and produce
automatically RDF/XMLs of these files ... for example.
(This is why I have come to be interested in POI and James)

-- Tetsuya Kitahata <ki...@bb.mbn.or.jp>



--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: about javadocs (was: Re: FW: What do we need to release 2.1?)

["Andrew C. Oliver" <ac...@apache.org>]

consider yourself upgraded in my book! ;-)

Danny Angus wrote:
>>or something as
>>fundamental as the correct documentation for how to setup a database URL
>>(which is correct in the CVS, and wrong in the current download).
> 
> 
> If this is the case it because the docs have been fixed.
> 
> And.. you should only consider the relevance of the stable "release"
> versions' documentation, the "latest" and "nightly" builds are strictly
> snapshots of work-in-progress, as such they should not be expected to
> function, nor should documentation be expected to be correct in any aspect.
> 
> Furthermore James has never released a Beta quality version yet, all the
> releases so far have, for various reasons, been considered to be Alpha
> quality code.
> 
> I subscribe to Andy's opinion that James is hard for a new user to get
> started with, because I have had to nursemaid many such users through their
> first experience with James.
> 
> In addition to documentation making life easier for users remember also that
> a +1 vote for a release binds the voter to support that release by
> participating on the developers and users lists. This is a great incentive
> to commiters to produce clear and accurate user documentation, and clear and
> accurate code documentation.
> 
> IMHO while the XP case for not documenting code is based in part upon the
> assumption that the code should be easy to follow and documentation  ca be
> used to avoid writing clear code, it does not follow that concise targeted
> code documentation obfuscates the code.
> 
> I rather believe that good javadoc documentation can encourage encapsulation
> and re-use by removing the necessity for programmers to concern themselves
> with the detail of code not directly relevant to the issues they are
> addressing, revealing method signatures and documenting their intended use
> cannot, surely, be counter productive, particularly in an OSS project.
> 
> Take a look at the Tomcat javadocs, they reveal the architecture of Tomcat
> in just enough detail for an outsider to extend and adapt the product,
> without explaining away bad practices, or forcing you to read the code
> itself.
> 
> I strongly believe that code documentation should be a halfway house between
> user documentation and the code itself, providing a convenient and easily
> navigable journey through the architecture, un-encumbered by the
> implementation details.
> 
> d.





--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: Bizzarre new bug...

["Noel J. Bergman" <no...@devtech.com>]

I'm lost.  What is the problem?  "? is being changed to ?"

As for the message body being recycled, isn't that what happens (not looking
at the code) when a new Mail object is created for a given subset of
recipients?

I'm sorry, but I really have no idea what this is about.

	--- Noel

-----Original Message-----
From: Danny Angus [mailto:danny@apache.org]
Sent: Monday, August 19, 2002 14:19
To: James Developers List
Subject: Bizzarre new bug...


? is being changed to ? in mail handled by James, in particular the message
body is being re-cycled into a new message.

Odd.
d.


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Bizzarre new bug...

[Danny Angus <da...@apache.org>]

? is being changed to ? in mail handled by James, in particular the message
body is being re-cycled into a new message.

Odd.
d.


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: James End User Documentation

["Andrew C. Oliver" <ac...@apache.org>]

On this we can all agree...  wikis are very powerful tools for 
generating documentation.  I'm very impressed with the progress made on 
the Cocoon wiki.  Stephen Noles (sp?) will be very suprised when he gets 
back from vacation.

-Andy

Noel J. Bergman wrote:
> Nicola,
> 
> Assuming that folks vote for a wiki, can we set one up on apache, or did
> this require a server elsewhere?
> 
> I like wikis.  Been running vqWiki on several projects.
> 
> 	--- Noel
> 
> -----Original Message-----
> From: Nicola Ken Barozzi [mailto:nicolaken@apache.org]
> Sent: Monday, August 19, 2002 15:25
> To: James Developers List
> Subject: Re: James End User Documentation
> 
> 
> 
> Noel J. Bergman wrote:
> 
>>>solicit away.
>>
>>
>> 1. Can we agree on some [DOCUMENTATION] prefix that people can use, so
> 
> that
> 
>>documentation submissions can be located in the archives?
>>
>> 2. How's:
>>
>>If you have James related tips, documentation bits, or just questions
> 
> about
> 
>>things that you need help with, please submit them to the James project
> 
> with
> 
>>a [DOCUMENTATION] prefix on the subject.  The more contributions, the
> 
> better
> 
>>the user documentation will get.
>>
>>I don't supposed anyone on the list is a tech writer, eh?  :-)
>>
>>I'll post up an example of multiple mailing lists so that people can see
>>what needs to be done for EACH new mailing list.  The current
> 
> documentation
> 
>>isn't clear on that (in fact, mine works but perhaps I missed a point).
> 
> 
> On the Cocoon project, we have already done this.
> 
> We started asking to commit doc stuff with [DOCS], then we moved to
> asking to put them in Bugzilla.
> 
> Finally we set up a Wiki, and this last solution brought us more
> documentation inh a week than the other two in a month!
> 
> --
> Nicola Ken Barozzi                   nicolaken@apache.org
>              - verba volant, scripta manent -
>     (discussions get forgotten, just code remains)





--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: James End User Documentation

["Noel J. Bergman" <no...@devtech.com>]

Nicola,

Assuming that folks vote for a wiki, can we set one up on apache, or did
this require a server elsewhere?

I like wikis.  Been running vqWiki on several projects.

	--- Noel

-----Original Message-----
From: Nicola Ken Barozzi [mailto:nicolaken@apache.org]
Sent: Monday, August 19, 2002 15:25
To: James Developers List
Subject: Re: James End User Documentation



Noel J. Bergman wrote:
>>solicit away.
>
>
>  1. Can we agree on some [DOCUMENTATION] prefix that people can use, so
that
> documentation submissions can be located in the archives?
>
>  2. How's:
>
> If you have James related tips, documentation bits, or just questions
about
> things that you need help with, please submit them to the James project
with
> a [DOCUMENTATION] prefix on the subject.  The more contributions, the
better
> the user documentation will get.
>
> I don't supposed anyone on the list is a tech writer, eh?  :-)
>
> I'll post up an example of multiple mailing lists so that people can see
> what needs to be done for EACH new mailing list.  The current
documentation
> isn't clear on that (in fact, mine works but perhaps I missed a point).

On the Cocoon project, we have already done this.

We started asking to commit doc stuff with [DOCS], then we moved to
asking to put them in Bugzilla.

Finally we set up a Wiki, and this last solution brought us more
documentation inh a week than the other two in a month!

--
Nicola Ken Barozzi                   nicolaken@apache.org
             - verba volant, scripta manent -
    (discussions get forgotten, just code remains)


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: James End User Documentation

[Nicola Ken Barozzi <ni...@apache.org>]

Noel J. Bergman wrote:
>>solicit away.
> 
> 
>  1. Can we agree on some [DOCUMENTATION] prefix that people can use, so that
> documentation submissions can be located in the archives?
> 
>  2. How's:
> 
> If you have James related tips, documentation bits, or just questions about
> things that you need help with, please submit them to the James project with
> a [DOCUMENTATION] prefix on the subject.  The more contributions, the better
> the user documentation will get.
> 
> I don't supposed anyone on the list is a tech writer, eh?  :-)
> 
> I'll post up an example of multiple mailing lists so that people can see
> what needs to be done for EACH new mailing list.  The current documentation
> isn't clear on that (in fact, mine works but perhaps I missed a point).

On the Cocoon project, we have already done this.

We started asking to commit doc stuff with [DOCS], then we moved to 
asking to put them in Bugzilla.

Finally we set up a Wiki, and this last solution brought us more 
documentation inh a week than the other two in a month!

-- 
Nicola Ken Barozzi                   nicolaken@apache.org
             - verba volant, scripta manent -
    (discussions get forgotten, just code remains)
---------------------------------------------------------------------


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

James End User Documentation

["Noel J. Bergman" <no...@devtech.com>]

> solicit away.

 1. Can we agree on some [DOCUMENTATION] prefix that people can use, so that
documentation submissions can be located in the archives?

 2. How's:

If you have James related tips, documentation bits, or just questions about
things that you need help with, please submit them to the James project with
a [DOCUMENTATION] prefix on the subject.  The more contributions, the better
the user documentation will get.

I don't supposed anyone on the list is a tech writer, eh?  :-)

I'll post up an example of multiple mailing lists so that people can see
what needs to be done for EACH new mailing list.  The current documentation
isn't clear on that (in fact, mine works but perhaps I missed a point).

	--- Noel


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: about javadocs (was: Re: FW: What do we need to release 2.1?)

[Danny Angus <da...@apache.org>]

> You did.  :-)  My question was about soliciting documentation 
> contributions.

solicit away.

--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: about javadocs (was: Re: FW: What do we need to release 2.1?)

["Noel J. Bergman" <no...@devtech.com>]

> > Would you mind if a message went out on James-User [asking]
> > them for contributions towards the [user] documentation?

> That should wait until we have a release plan

OK

> (I thought I did announce the build, if not feel free to repeat it)

You did.  :-)  My question was about soliciting documentation contributions.

	--- Noel


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: about javadocs (was: Re: FW: What do we need to release 2.1?)

[Danny Angus <da...@apache.org>]

> Thank you.  Would you mind if a message went out on James-User
> telling folks
> that we're working towards a new Release Build, and asking them for
> contributions towards the documentation?  They could contribute
> actual bits
> of documentation, or just questions that they are having trouble with.

That should wait until we have a release plan, and are happy that we have a
release candiidate, which we can release for testing and annouce the planned
release.

(I thought I did announce the build, if not feel free to repeat it)

d.


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: about javadocs (was: Re: FW: What do we need to release 2.1?)

["Noel J. Bergman" <no...@devtech.com>]

> > If 2.1aX is an improvement, as we all seem to believe
> > that it is

> We don't, or at least _I_ didn't until two days ago

I didn't think so either, until recently.  And I'm NOT saying that it is
ready today, either, because there ARE issues that should be resolved before
the Release Build.  The question is what are the items to be done to get it
that way.  That was the question Peter raised in his initial post, and the
question you raised again in your post of a few minutes ago.  :-)

> the user documentation and open bugs (still being actively discussed)

Both are things that I agree need to be addressed.

> IMHO 2.1.1 is *not* an improvement until the documentation that
> accompanies it is of an acceptable standard to at least avoid
> leading people astray, even if it isn't actually helpful.

Agreed.

> If you're refering to a milestone, its already been made.

Thank you.  Would you mind if a message went out on James-User telling folks
that we're working towards a new Release Build, and asking them for
contributions towards the documentation?  They could contribute actual bits
of documentation, or just questions that they are having trouble with.

I'll post up an example of multiple mailing lists so that people can see
what needs to be done for EACH new mailing list.  The current documentation
isn't clear on that (in fact, mine works but perhaps I missed a point).
Should such contributions be posted to James-Dev or James-User?

> I don't believe that we javadocs are a showstopper, but neither do I
believe
> that they should be swept under the carpet.

That is exactly what I have been saying, Danny.  No one is sweeping javadocs
under the carpet, or deferring them.  They are being worked on actively.
Andrew has been arguing vociferously that they are a showstopper, and that's
the point of disagreement.

	--- Noel


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: about javadocs (was: Re: FW: What do we need to release 2.1?)

[Danny Angus <da...@apache.org>]

> Exactly.  The CVS has corrected documentation that should be made
> available
> to the user community.

Up to date documentation is available on the website, this is common
practice.
Unless we seperate the release of docs from code its unavoidable, not least
because we're bound to increment release numbers by the jakarta standards we
can't patch a release once its been made, and incrementing release numbers
to patch docs would lead to a flood of email asking us what exactly had
changed in the product..

> The fact remains that 2.0a3 is out there as a Release Build.  For
> better or
> for worse.  If 2.1aX is an improvement, as we all seem to believe
> that it is

No, actually we don't, or at least _I_ didn't until two days ago, and even
then there are still the user documentation and open bugs (still being
actively discussed) to be dealt with notwithstanding the javadocs. IMHO
2.1.1 is *not* an improvement until the documentation that accompanies it is
of an acceptable standard to at least avoid leading people astray, even if
it isn't actually helpful.

> (or is close to being), then it should be put out as the next incremental
> step on the road.

If you're refering to a milestone, its already been made.

I don't believe that we javadocs are a showstopper, but neither do I believe
that they should be swept under the carpet.
Once the precendent has been establised to defer unpopular tasks it is hard
to instil any urgency in them.
I believe that we should certainly be considering the javadocs when we vote,
as well as the user docs, website and functionality.
What emphasis each commiter gives to that will be reflected in their vote.

d.


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: about javadocs (was: Re: FW: What do we need to release 2.1?)

["Noel J. Bergman" <no...@devtech.com>]

> > how to setup a database URL (which is correct in the
> > CVS, and wrong in the current download).

> If this is the case it because the docs have been fixed.

Exactly.  The CVS has corrected documentation that should be made available
to the user community.

> you should only consider the relevance of the stable "release"
> versions' documentation

I was refering to 2.0a3, which IS the latest "stable Release Build."

> Furthermore James has never released a Beta quality version yet,

Perhaps not, but in Apache terminology, James 2.0a3 is a Release Build.  If
you are saying that James should never have had a Release, only a Milestone,
I won't argue the point.

> I subscribe to Andy's opinion that James is hard for a new user to get
> started with ...

So do I.  But that has to do with end user documentation, not javadocs,
except for the headers on Matchers & Mailets that contain samples, which
I've been fixing as I spot them.

On the one hand, Andy is taking an all-or-nothing position on javadocs (if
we don't have them all, we have nothing); on the other hand, he said "If I
weren't a semi-decent Java developer I couldn't even set up JAMES."

Contrary to his accusations, I've recently found, fixed and documented
various issues involving the spooler (locking, the mysterious NPE, the
reason why a message might no longer be in the spool after accept() gives it
to you); the potential for an infinite loop involving Forward;
address-literals; discrepancies between RFCs and the size of database
fields; and more.  Fortunately, I have a sense of humor.

> a +1 vote for a release binds the voter to support that release

A good policy.  :-)  I've been doing that even without a vote.  And that's
why I want to see a new release, because it will be easier to support.

As for the javadocs, I agree with everything you said about the value of
code documentation.  In every case, everyone says that it is important, no
one has said anything about not documenting or slowing documentation.  The
only issue is whether or not to update what is currently published with what
is available.  It is a matter of improvement while continuing towards
perfection.

The fact remains that 2.0a3 is out there as a Release Build.  For better or
for worse.  If 2.1aX is an improvement, as we all seem to believe that it is
(or is close to being), then it should be put out as the next incremental
step on the road.  Andy views that statement as tantamount to dismissing
javadocs as worthless.  I view his approach as being roughly the same as
saying my transmission needs an overhaul so I'll skip the oil changes until
I can afford to pay for the major service.  Both things need to be done, and
are continuing apace.

	--- Noel


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: about javadocs (was: Re: FW: What do we need to release 2.1?)

[Danny Angus <da...@apache.org>]

> or something as
> fundamental as the correct documentation for how to setup a database URL
> (which is correct in the CVS, and wrong in the current download).

If this is the case it because the docs have been fixed.

And.. you should only consider the relevance of the stable "release"
versions' documentation, the "latest" and "nightly" builds are strictly
snapshots of work-in-progress, as such they should not be expected to
function, nor should documentation be expected to be correct in any aspect.

Furthermore James has never released a Beta quality version yet, all the
releases so far have, for various reasons, been considered to be Alpha
quality code.

I subscribe to Andy's opinion that James is hard for a new user to get
started with, because I have had to nursemaid many such users through their
first experience with James.

In addition to documentation making life easier for users remember also that
a +1 vote for a release binds the voter to support that release by
participating on the developers and users lists. This is a great incentive
to commiters to produce clear and accurate user documentation, and clear and
accurate code documentation.

IMHO while the XP case for not documenting code is based in part upon the
assumption that the code should be easy to follow and documentation  ca be
used to avoid writing clear code, it does not follow that concise targeted
code documentation obfuscates the code.

I rather believe that good javadoc documentation can encourage encapsulation
and re-use by removing the necessity for programmers to concern themselves
with the detail of code not directly relevant to the issues they are
addressing, revealing method signatures and documenting their intended use
cannot, surely, be counter productive, particularly in an OSS project.

Take a look at the Tomcat javadocs, they reveal the architecture of Tomcat
in just enough detail for an outsider to extend and adapt the product,
without explaining away bad practices, or forcing you to read the code
itself.

I strongly believe that code documentation should be a halfway house between
user documentation and the code itself, providing a convenient and easily
navigable journey through the architecture, un-encumbered by the
implementation details.

d.


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: about javadocs (was: Re: FW: What do we need to release 2.1?)

["Noel J. Bergman" <no...@devtech.com>]

> Undocumented non-quality code is NOT pragmatic... in fact:
> http://www.pragmaticprogrammer.com/cgi-local/pragprog?FailureHowTo

I like how you imply that the James is undocumented and non-quality just
because an effort is being made to improve the quality and consistency of
the comments.

James' code isn't undocumented, but there are various uncommented members,
so Peter is trying to complete the documentation.  The same can be said of
org.apache.poi.  For example, AbstractFunctionPtg is missing javadocs for a
number of members.

The wiki you pointed to says "Write no JavaDoc (for instance) or any
documentation whatsoever."  It doesn't apply.  No one ever said "don't do
documentation."

> Javadoc to me is so basic and takes so little time, to
> actually argue against it...

Are you actually reading these messages, or responding to some imagined
offense?  No one has argued against writing javadocs, which is an active,
on-going process.  The only issue is whether or not to wait for that process
to finish before we update an old, out-of-date, package with a new package
that fixes bugs in both code and documentation that are causing problems for
people on a daily basis.

> To me this is the same as an argument to write variables a1, a2, a3

This kind of hyperbole suggests that you're really reacting to something
unrelated to anything actually going on here.  Some projects from your past,
perhaps.

And, of course, this has nothing to do with end user documentation, such as
telling a user how to install and deploy James.  You know, little things
like how to setup a mailing list (have fun reading the docs and FAQ), how
different matchers and mailets interact with each other, or something as
fundamental as the correct documentation for how to setup a database URL
(which is correct in the CVS, and wrong in the current download).

	--- Noel


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: about javadocs (was: Re: FW: What do we need to release 2.1?)

["Andrew C. Oliver" <ac...@apache.org>]

> 
> No, I'm pragmatic and you just don't like it.  This isn't about some ivory
> tower notion of what makes good code.  This is about lots of James users who
> are stuck using buggy code and bad documention while we sit here using the
> good stuff and arguing over when to deliver it to them.
> 
> 
>>What good is a release to a user if he can't make hide nor hair of it?
>>If I weren't a semi-decent Java developer I couldn't even set up JAMES.
> 
> 
> I agree with you, but what does this have to do with javadocs, Andy?  Talk
> about end user documentation and we'd be agreeing, because what good are
> javadocs to the average user?
> 

Its the whole package.  Code complete.  You're not pragmatic. 
Undocumented non-quality code is NOT pragmatic... in fact:

http://www.pragmaticprogrammer.com/cgi-local/pragprog?FailureHowTo

Fine to release a development build, but don't lie and call something a 
release, you do everyone a disservice.

-Andy


> 	--- Noel





--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: about javadocs (was: Re: FW: What do we need to release 2.1?)

["Andrew C. Oliver" <ac...@apache.org>]

Yeah, I don't see a problem with that.  its with an actual release.

Danny Angus wrote:
> If thats what you want to do we can put out another dated 2.1a1.
> d.
> 
> 
>>>As I said in another e-mail, let's put out a 2.1a2 Milestone Build to
>>>replace the ancient May 30 2.1a1 Milestone, and I'll feel much 
>>
>>better for
>>
>>>our end users.
>>>
>>>	--- Noel
>>
>>
>>
>>
>>
>>--
>>To unsubscribe, e-mail:   
> 
> <ma...@jakarta.apache.org>
> For additional commands, e-mail: <ma...@jakarta.apache.org>





--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

New "latest" build available

[Danny Angus <da...@apache.org>]

There is now a new dated build of the HEAD of CVS in
http://jakarta.apache.org/builds/jakarta-james/latest/
This is a snapshot of recent changes for evaluation, and should not be
considered to be a stable release.

d.


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: What do we need to release 2.1

["Andrew C. Oliver" <ac...@apache.org>]

I'm willing to set up a wiki for james on my server if needed.  I'd do 
it on jakarta.apache.org but I don't believe we have a cgi-bin 
directory.  If there is consensus on this let me know and I'll be happy 
to do it.

Noel J. Bergman wrote:
> Does a template for such a release plan exist from previous releases?
> 
> Peter's issues were expressed in his original post:
> http://www.mail-archive.com/james-dev@jakarta.apache.org/msg03100.html,
> which kicked off this round of discussion.  Other folks have added their
> viewpoints, which can be found in the archives.  Now that we've updated the
> Milestone build, I'd amend some of my earlier points.
> 
> This is a case where a Wiki would be a useful tool as the details of the
> release plan are hashed out.
> 
> 	--- Noel
> 
> -----Original Message-----
> From: Danny Angus [mailto:danny@apache.org]
> Sent: Monday, August 19, 2002 11:43
> To: James Developers List
> Subject: What do we need to release 2.1
> 
> 
> Ok,
> 
> 1/ we need a release plan, circulated to this list or put into cvs then put
> to a vote.
> 
> Should include all steps needed to make a release, including..
> 
> issue management, fix, close or defer all open bugs.
> build & test, make a release candidate available to canvas widest testing
> audience
> 
> Vote on progress to the next step after completion of issue management.
> 
> update all documentation
> update website
> build, upload, announce
> 
> d.





--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: What do we need to release 2.1

["Noel J. Bergman" <no...@devtech.com>]

Does a template for such a release plan exist from previous releases?

Peter's issues were expressed in his original post:
http://www.mail-archive.com/james-dev@jakarta.apache.org/msg03100.html,
which kicked off this round of discussion.  Other folks have added their
viewpoints, which can be found in the archives.  Now that we've updated the
Milestone build, I'd amend some of my earlier points.

This is a case where a Wiki would be a useful tool as the details of the
release plan are hashed out.

	--- Noel

-----Original Message-----
From: Danny Angus [mailto:danny@apache.org]
Sent: Monday, August 19, 2002 11:43
To: James Developers List
Subject: What do we need to release 2.1


Ok,

1/ we need a release plan, circulated to this list or put into cvs then put
to a vote.

Should include all steps needed to make a release, including..

issue management, fix, close or defer all open bugs.
build & test, make a release candidate available to canvas widest testing
audience

Vote on progress to the next step after completion of issue management.

update all documentation
update website
build, upload, announce

d.



--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

What do we need to release 2.1

[Danny Angus <da...@apache.org>]

Ok,

1/ we need a release plan, circulated to this list or put into cvs then put
to a vote.

Should include all steps needed to make a release, including..

issue management, fix, close or defer all open bugs.
build & test, make a release candidate available to canvas widest testing
audience

Vote on progress to the next step after completion of issue management.

update all documentation
update website
build, upload, announce

d.



--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

New "latest" build available

[Danny Angus <da...@apache.org>]

There is now a new dated build of the HEAD of CVS in
http://jakarta.apache.org/builds/jakarta-james/latest/
This is a snapshot of recent changes for evaluation, and should not be
considered to be a stable release.

d.


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: about javadocs (was: Re: FW: What do we need to release 2.1?)

[Danny Angus <da...@apache.org>]

If thats what you want to do we can put out another dated 2.1a1.
d.

> > As I said in another e-mail, let's put out a 2.1a2 Milestone Build to
> > replace the ancient May 30 2.1a1 Milestone, and I'll feel much 
> better for
> > our end users.
> > 
> > 	--- Noel
> 
> 
> 
> 
> 
> --
> To unsubscribe, e-mail:   
<ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: about javadocs (was: Re: FW: What do we need to release 2.1?)

["Noel J. Bergman" <no...@devtech.com>]

> I totally disagree with just about everything Noel said except for the
> end.

> As long as everyone understands that documentation is as important as
> code and that poorly documented code is just pure rat dung.

> Code complete, means docs too.

That may be your philosophy, and it might even be one that I share.  But
we're not the ones being screwed.  The end users are.  You want to incent
developers, find another way.  But I suggest that at the moment, Peter is
doing a great job of fixing years of neglect.

> Noel, you're wrong

No, I'm pragmatic and you just don't like it.  This isn't about some ivory
tower notion of what makes good code.  This is about lots of James users who
are stuck using buggy code and bad documention while we sit here using the
good stuff and arguing over when to deliver it to them.

> What good is a release to a user if he can't make hide nor hair of it?
> If I weren't a semi-decent Java developer I couldn't even set up JAMES.

I agree with you, but what does this have to do with javadocs, Andy?  Talk
about end user documentation and we'd be agreeing, because what good are
javadocs to the average user?

	--- Noel


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: about javadocs (was: Re: FW: What do we need to release 2.1?)

["Andrew C. Oliver" <ac...@apache.org>]

I totally disagree with just about everything Noel said except for the 
end.  Development builds "milestone builds" or whatever, should not be 
delayed for quality concerns.  It just can't be blessed as a release.

As long as everyone understands that documentation is as important as 
code and that poorly documented code is just pure rat dung.  IF you 
don't Javadoc, you are a crappy no good developer.  Code complete, means 
docs too.

Noel, you're wrong, once releases are the "gold standard" developers 
care.  What good is a release to a user if he can't make hide nor hair 
of it?  If I weren't a semi-decent Java developer I couldn't even set up 
JAMES.  That puts JAMES a bit behind most other mail servers.  If a 
developer doesn't care about that, then there isn't much he could care 
about.  I've seen projects where the documentation was tied to the 
*real* release and the developers DID care.

-Andy



Noel J. Bergman wrote:
> Peter,
> 
> I agree with almost all of your points.  The only ones that I disagree with
> are:
> 
> 
>>observation of the changelog indicates, leaving javadoc out vs.
>>adding javadoc has not made the development any faster.
> 
> 
> I disagree, in a way that you'll like.  I think that accurate javadocs
> facilitates development.
> 
> 
>>I also suggested that the internal documentation be tied to a release
> 
> because:
> 
>>i) That way it actually gets done
> 
> 
> Only because you want to get it done.  Practically, it just doesn't work
> that way.  Developers already have access to the current code, so if they
> don't care about the javadocs, holding a release up isn't an incentive for
> them to do it.  And you don't need the incentive, you are doing it anyway.
> 
> 
>>ii) When the release announcement spurs a few developers to take a look
>>at the code base, they'll find a well-documented, inviting code base.
> 
> 
> I support that goal.
> 
> As I said in another e-mail, let's put out a 2.1a2 Milestone Build to
> replace the ancient May 30 2.1a1 Milestone, and I'll feel much better for
> our end users.
> 
> 	--- Noel





--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: about javadocs (was: Re: FW: What do we need to release 2.1?)

["Noel J. Bergman" <no...@devtech.com>]

Peter,

I agree with almost all of your points.  The only ones that I disagree with
are:

> observation of the changelog indicates, leaving javadoc out vs.
> adding javadoc has not made the development any faster.

I disagree, in a way that you'll like.  I think that accurate javadocs
facilitates development.

> I also suggested that the internal documentation be tied to a release
because:
> i) That way it actually gets done

Only because you want to get it done.  Practically, it just doesn't work
that way.  Developers already have access to the current code, so if they
don't care about the javadocs, holding a release up isn't an incentive for
them to do it.  And you don't need the incentive, you are doing it anyway.

> ii) When the release announcement spurs a few developers to take a look
> at the code base, they'll find a well-documented, inviting code base.

I support that goal.

As I said in another e-mail, let's put out a 2.1a2 Milestone Build to
replace the ancient May 30 2.1a1 Milestone, and I'll feel much better for
our end users.

	--- Noel


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

RE: about javadocs (was: Re: FW: What do we need to release 2.1?)

["Peter M. Goldstein" <pe...@yahoo.com>]

Vincent,

I'm not offended, although I disagree almost entirely with your points.
:)

Basically I feel that on distributed, volunteer projects extensive and
appropriate documentation is even more important than on projects being
done by a full-time, localized development team.  And I feel that it is
extremely important even in the latter case.

While XP is an interesting methodology, James is in no way an XP
project.  We are using none of the XP techniques (pair programming,
rapid rotation of developers to different parts of the code base,
aggressive refactoring of unclear code etc.) that make internal
documentation far less important.  And as observation of the changelog
indicates, leaving javadoc out vs. adding javadoc has not made the
development any faster.

I believe that one of the essential things an open source project must
do is attract developers.  You do that by making the projects
interesting, and the code easy to understand.  To me, that means
internal documentation.  That's what allows a new developer to come up
to speed in a very short time and participate productively in the
project.  And on this point at least the Apache code standards seem to
agree with me.  :)

I also suggested that the internal documentation be tied to a release
because:

i) That way it actually gets done
ii) When the release announcement spurs a few developers to take a look
at the code base, they'll find a well-documented, inviting code base.

I'd be happy to continue this discussion offline, but I stand by my
original wish list entry.  

--Peter

> -----Original Message-----
> From: Vincent Keunen [mailto:vincent.keunen@manex.be]
> Sent: Sunday, August 18, 2002 7:13 AM
> To: James Developers List
> Subject: about javadocs (was: Re: FW: What do we need to release 2.1?)
> 
> Thanks Peter, for your message that makes things move forward.  I'm
> adding some comments about the specific item of javadocs.  First, I
must
> say that I agree with 2 comments from Noel:
> 
> > Internal Documentation
> > Absolutely necessary. But NOT to hold up the 2.1 release. We can
> continue
> > to upgrade the web site with new documentation, and any serious
> developer
> > should be working from the CVS
> 
> 
> and
> 
> > At least get the javadoc complete.
> >
> > javadocs are for developers. I view 2.1 as a RELEASE build for
users.
> Yes,
> > we need to work on the javadocs, but I would not wait for them
before
> > putting out a stable release build if we can do so.
> >
> Peter M. Goldstein wrote:
> 
> >Internal Documentation
> >
> >I know some people tend to dismiss internal documentation, but I
don't
> >see how a project that is seeking to attract developers can function
> >without it.  As such I tend to include it in the exit criteria for a
> >particular release.
> >
> >1) All methods and instance variables should be documented.  All
classes
> >should be documented.  The documentation doesn't need to be
extensive,
> >but it should be present.  It should include issues such as
class/method
> >contracts and threading restrictions where appropriate.
> >2) All public and protected classes, methods, and variables need to
be
> >documented using Javadoc style to ensure appropriate Javadoc
> >3) The Javadoc should build without warnings
> >4) All packages should have package documentation
> >
> >
> >
> Peter, I'd like to modify a bit your suggestion.  From my experience
(15
> years of OO software developement), doc should be reduced to the
minimum
> (and I find XP discussions about documenting the code quite
appropriate
> to modern developments).  Some ideas:
> 
>     * code is the only thing that really lives; it changes often
>       (writing docs is time consuming and is very difficult to keep in
>       sync with the code; and out of sync doc is useless, and may even
>       lead you to wrong assumptions...)
>     * the code (at the class/method level) should be self explicit: if
>       you need doc to explain code, think about rewriting code to make
>       it more explicit; also, good developers read code almost as
easily
>       as the doc (if the code is good, of course)
>     * doc is very useful at the package level: "what does this package
>       contain, where to look first" (important classes and methods
>       should be mentionned)
>     * important classes/methods may need some doc
>     * important here meaning "part of an API, important for external
>       developers" or "part of the basic building blocks of the system,
>       that all developers should be comfortable with"
> 
> I really don't want to start a lengthy discussion on the pros and cons
> of documentation (see the forum related to that), but I believe that
> docs should not get in the way of developing fast (especially on a
> volunteer basis, with restrained resources).  And I am convinced that
it
> won't hurt the project's perennity...
> 
> Just my 2 cents (and I hope I did not offense you, Peter).
> 
> --
> !try; do()
> --
> Vincent Keunen, Ir, http://vincent.keunen.net
> Manex, rue Wagner 93, BE-4100 Boncelles, Belgium
> Our site: http://www.manex.be




--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>