commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gary Gregory <ggreg...@seagullsw.com>
Subject RE: [release docs] some thoughts
Date Thu, 17 Jul 2003 21:24:57 GMT
Hello,

For small scale components, like a FooUtils or any class that can be used in
a standalone manner, I have found *extremely* useful to have nice Javadoc
comments with *code examples*. I would like to encourage all contributors to
keep this in mind.

This type of stuff also depends on your philosophical approach to unit
testing vs Javadoc'ing. I've read things like: The unit test should be
consulted for usage and examples. For me this does not quite cut it.

Gary

-----Original Message-----
From: robert burrell donkin [mailto:robertburrelldonkin@blueyonder.co.uk] 
Sent: Thursday, July 17, 2003 13:47
To: Jakarta Commons Developers List
Subject: Re: [release docs] some thoughts

i'd like to encourage people to submit comments and improvements ASAP. i 
will move things around soonish so that these are linked at the main 
how-to-release documents.

On Tuesday, July 15, 2003, at 12:56 AM, Henri Yandell wrote:

> Couple of thoughts on Robert's release documentation at:
>
> http://jakarta.apache.org/commons/releases/
>
> In prepare.html, the manifest description doesn't quite match Sun's. They
> don't mention 'Extension-Name'

this is to do with the java extension mechanism but i forget now exactly 
why it's in there. tradition, quite probably. i've done a quick search and 
the best link i can find it 
http://marc.theaimsgroup.com/?l=jakarta-commons-dev&m=101804864505521&w=2.

> and they say to include the Manifest version.

yep. missed that out.

> In release.html, it has the builder building the release version in
> their own sandbox. I would recommend that instead it suggest the builder
> checkout the particular tag into their new working directory and perform
> the build there.

that's what i do. probably didn't make that clear

> The entire source tree does not always want to go into
> the build.

the entire source tree shouldn't go into the build. but what goes into the 
build should be controlled by the build process, shouldn't it?

(or maybe i'm a little confused.)

> Then after the binaries have been built, I would recommend
> releasing and re-checking out to create the sources.

the new follow's craig original quite closely for the source build. it 
says create a temporary directory and then export (rather than checkout) 
the source. is this what you mean?

> Also, a -q on the zip -r will be appreciated by the builder :)

i like it noisey ;)

want to volunteer to patch these documents?

- robert


---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message