Re: cvs commit: jakarta-site2/docs/site dirlayout.html

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

At 06:56  13/3/01 -0000, ceki@apache.org wrote:
>   <td>src/</td>
>   <td>Source code.</td>
>  
>   <td>If the source code contains only code in the Java language, then
>   the contents of the src/ directory should mirror the package
>   hierarchy. Otherwise, if the code contains a mix of languages, then
>   an extra directory level could be used to separate source code by
>   language, as in src/java/ and src/php for source code in the java and
>   php languages respectively.

All projects will eventually grow to carry some form of cross language
revision control. Many projects will include sql scripts/config
scripts/content (ie jsp/vml pages). I would put everything that has
possibility of being modified during build process under src/<type>/* where
type can be separation by media type (ie java/sql or funciton like
testcases/compat).

Furthermore even if a project requires no extra medias currently it may in
the future. As CVS is incapable of understanding move command I would thus
recomend that all projects start out with

sr/<type>/ hierarchy even if they have only one type.  

>   <tr>
>   <td>xdocs/</td>
>   <td>Documentation file in XML format.</td>
>  
>   <td>The Jakarta site uses Velocity/Anakia to transform dcumentation
>   files in XML into HTML. The generated HTML files automatically
>   inherit the Jakarta look-and-feel.
>   </td>
>   <td>YES</td>
>   </tr>

I would place this under src/xdocs as many projects modify docs during
build process (via replacing constants-tokens-whatever).

>   </tr>
>   
>   <tr>
>   <td>build/</td>
>   <td>Files required for building the sub-project.</td>
>  
>   <td>Building includes compiling source code, generating javadoc
>   documentation, the creation of jar files and the distribution files
>   in tar.gz or zip formats.
>   </td>
>   <td>YES</td>
>   </tr>

As the eventual goal of many tool projects is not to be included in CVS
(hopefully CJAN will fix this) I don't like this mixing of concerns (ie
tools with other project specific build facilities). Thus I would instead
recomend an alternate hierarchy for tools. ie

tools/bin/* (contains generic scripts + binaries - like antRun)
tools/lib/* (contains generic jars - like stylebook/anakia/ant)

I would also place the wrapper build scripts along with main build project
file into base directory. That way newbies can understand build process
simply without any understanding of build hierarchy. It also mirrors the
way other tools and projects work thus minimizing warm up time.

Another point to make is that the build/ directory is used by a few
projects for temporary/intermediate files 

>   <tr>
>   <td>dist/</td> 
>  
>   <td>Generated jar files and other sub-project binaries.</td>
>  
>   <td>This directory contains jar files for the
>   sub-project. Distribution binaries in .tar.gz and .zip formats should
>   also be placed in this directory.
>   </td>
>   <td>NO</td>
>   </tr>

I would instead break this into three directories.

distributions/
dist/
src-dist/

dist contains an image of binary dist, src-dist of source distribution and
distributions contain the .tar.gz/.zip/.rpm files. The reason is that many
projects create an intermediate version that is runnable in the directory
via something like

prompt> cd dist/bin
prompt> run.[sh|bat]

But need different directories when building distributions for releases.

>   <tr>
>   <td>dist/classes/</td>
>   <td>Class files generated from the source code contained in the src/
>   directory.</td>
>   <td>Other binary files such as icons and images should also be placed
>   under dist/classes/.

I would remove the last line as it is no longer necessary with ant (yay for
zipfilesets). Besides what does a set of classes have to do with a
distribution (they are not normally contained loose in a dist file).

>   <tr>
>   <td>contribs/</td>
>   <td>Contributions not officially part of the sub-project.</td>
>   <td>Some projects use other names such as whiteboard/ or proposals/.

Contrib and whiteboard/proposals are different things. whiteboard/proposals
is used for proposing forks/revolutions and working on them in the interim
until accepted or -1'ed. contrib is for code that the devs don't want to
take responsibility for ;)

>  <section name="ANT build files">
>  
>  <p>Should we also include directives for ANT build scripts, common
>  target names, etc. in this document?

+1 Yep
Cheers,

Pete

*-----------------------------------------------------*
| "Faced with the choice between changing one's mind, |
| and proving that there is no need to do so - almost |
| everyone gets busy on the proof."                   |
|              - John Kenneth Galbraith               |
*-----------------------------------------------------*


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