donaldp 01/03/21 01:23:15
Modified: xdocs/site dirlayout.xml
Log:
Update dirlayout with my take on it
Revision Changes Path
1.7 +72 -81 jakarta-site/xdocs/site/dirlayout.xml
Index: dirlayout.xml
===================================================================
RCS file: /home/cvs/jakarta-site/xdocs/site/dirlayout.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- dirlayout.xml 2001/03/20 19:48:43 1.6
+++ dirlayout.xml 2001/03/21 09:23:14 1.7
@@ -4,6 +4,7 @@
<properties>
<author email="[EMAIL PROTECTED]">Ceki Gülcü</author>
<author email="[EMAIL PROTECTED]">Jon S. Stevens</author>
+ <author email="[EMAIL PROTECTED]">Peter Donald</author>
<title>Jakarta Directory Layout</title>
</properties>
@@ -48,7 +49,7 @@
<tr>
<td>LICENSE.txt</td>
- <td>A copy of the Apache Public License</td>
+ <td>A copy of the Apache License</td>
<td>The LICENSE.txt should be placed at a prominent location.
This file should have the suffix .txt so that it can be opened
@@ -63,9 +64,9 @@
<td><p>The code may be placed into separate source code directories
by language, as in src/java/ and src/php/ for source code in the Java
- and PHP languages respectively. Some Jakarta projects organize source
- code differently but in all cases source code is placed under the
- src/ directory.</p>
+ and PHP languages respectively. Other projects may separate the code
+ according to function (src/share, src/testcases, src/compat). It is
+ highly recomended that sub-directories be used under src/.</p>
</td>
<td>YES</td>
@@ -76,33 +77,52 @@
<td>src/xdocs/</td>
<td>Documentation files 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. Documentation is <a
+ <td>The Jakarta site uses Velocity/Anakia or Stylebook to transform
+ dcumentation files in XML into HTML. The generated HTML files automatically
+ inherit the Jakarta look-and-feel. Documentation is <a
href="./jakarta-site2.html">available</a>.
</td>
<td>YES</td>
</tr>
-
<tr>
<td>docs/</td>
<td>Documentation files intended for the end user.</td>
<td>The docs/ directory contain most of the documentation for the
- Jakarta sub-project. This includes Velocity/Anakia generated HTML
- files. This directory may also contain other documentation files.
- Generally, all documentation is stored in the src/xdocs/ directory
- and then "transformed" into this directory. It is then checked into
+ Jakarta sub-project. This includes Velocity/Anakia or Stylebook
+ generated HTML files. This directory may also contain other
+ documentation files. Generally, all documentation is stored in the
+ src/xdocs/ directory and then "transformed" into this directory.
+
+ It is then checked into
CVS and checked out of CVS on the live website. This allows the user
to browse the documentation on the local host without requiring
- network connectivity as well as on the live website.
+ network connectivity as well as on the live website. Alternatively
+ some projects may place
</td>
+ <td>NO</td>
+ </tr>
+
+ <tr>
+ <td>docs/ or www/</td>
+ <td>Web site documentation.</td>
+
+ <td>Some projects choose to check in documentation for their website
+ to ease maintanence of site. This may be a superset of the documentation
+ included in the documentation provided in distributions. If the project
+ includes regular distributions then the website should be an image of
+ documentation of last release. For projects that don't have regular releases
+ and whos website does not have highly volatile information (news, bug reports
+ etc.) then it is acceptable to use docs/ subdirectory otherwise the www/ directory
+ is recomended. Once checked into the CVS it is expected that the documentation will
+ also be checked out on live website.
+ </td>
<td>YES</td>
</tr>
<tr>
- <td>docs/index.html</td>
+ <td>www/index.html</td>
<td>Starting point for browsing the documentation.</td>
<td>Browsing the documentation locally should yield the same results
@@ -113,7 +133,7 @@
</tr>
<tr>
- <td>docs/api/</td>
+ <td>docs/api</td>
<td>API documentation as generated by the Javadoc tool.</td>
<td>Placing the API documenation under docs/api/ makes it slightly
@@ -128,18 +148,18 @@
</tr>
<tr>
- <td>build/</td>
+ <td>tools/ or 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>
<td>YES</td>
</tr>
<tr>
- <td>build/build.xml</td>
+ <td>build.xml or build/build.xml</td>
<td>The ANT build script.</td>
<td>All Jakarta projects are required to use ANT as their build tool.
@@ -149,29 +169,27 @@
<td>YES</td>
</tr>
-
<tr>
- <td>build/build.sh build/build.bat</td>
+ <td>build.sh build.bat</td>
<td>Shell scripts for Unix and DOS environments to bootstrap the ANT
build process.</td>
<td>The existence of these files implies the existence of binary jar
files, such as ant.jar and xerces.jar under CVS control
- Note, it is allowable to place the shell scripts at the top level
- directory structure.
+ Note, it is allowable to place the shell scripts in subdirectory build/.
</td>
<td>YES</td>
</tr>
<tr>
- <td>build/lib/</td>
+ <td>tools/lib or build/lib/</td>
<td>Binary jar files required for building the sub-project.</td>
<td>The jar files are added to the classpath by the bootstrapping
shell scripts before invoking ANT. The jar files should consist of
ant.jar as well as jar files needed for XML parsing.
- <p>The build/lib/ directory should contain jar files needed during
+ <p>The tools/lib/ or build/lib/ directory should contain jar files needed during
build time and during build time only. If an XML parser
is also required during the runtime of the project, then the jar
files for the parser should be placed under dist/lib/.</p>
@@ -183,101 +201,75 @@
<tr>
<td>dist/</td>
- <td>This directory contains most of the binaries related with the
- sub-project, generated or not.</td>
+ <td>This directory is an image of the distribution files. Hence why it is called
"dist" (short
+ for distribution).</td>
<td>The contents of the dist/ directory should be enough to use the
- project.
+ project. The particular format of distribution is project dependent. Some may
generate
+ a project.jar and a README while others may have dist the image of a .war file. It
is
+ commong to have dist/bin for scripts and dist/lib for jars related to runtime.
</td>
<td>NO</td>
</tr>
-
- <tr>
- <td>dist/bin/</td>
-
- <td>Scripts and executables that the end-user will invoke to run the
- project.</td>
- <td>A one-stop location to run the project as an application.</td>
- <td>NO</td>
- </tr>
-
- <tr>
- <td>dist/lib/</td>
-
- <td>.jar or other library files that the project
- depends on during runtime.</td>
-
- <td>This directory and the build/lib/ directories are used to store
- library files that the project depends on at runtime.
- </td>
-
- <td>YES</td>
- </tr>
-
<tr>
- <td>dist/classes/</td>
- <td>Class files generated from the source code contained in the src/
- directory.</td>
-
- <td><p>In other words, when the project is compiled, the output
- directory should be this directory.</p>
-
- <p>Other binary files such as icons and images may also be placed
- under dist/classes/. The contents of this directory can be used to
- generate jar files.</p>
+ <td>bin/ or build/</td>
+ <td>Intermediate files files generated while building the project.</td>
- <p>Note that including raw classes in a distribution will waste
- network bandwidth as well as disk space.</p>
+ <td><p>It is to this directory that intermediate files are generated.
+ Different types are generally generated to sub-directories (ie .class files
+ stored in bin/classes, build/classes, .jar files in bin/lib or build/lib.</p>
</td>
<td>NO</td>
</tr>
-
<tr>
- <td>dist/release/</td>
+ <td>distributions/</td>
- <td>This directory contains the project release binaries in .tar.gz
- and .zip format.</td>
+ <td>This directory contains the project release distributions. These are often
+ project.tar.gz, project.zip, project.rpm or project.war format.</td>
<td>
- <p>A project release typically consists of build scripts, source
- code, documentation including javadoc generated documentation, jar
- files required at runtime or everyting that an end-user needs to
- successfully use the project.
- </p>
+ <p>There are generally two forms of releases. Binary releases and
+ source releases. Binary releases consist of all the components end-users
+ require to use the product. This may include jars and generated documentation.</p>
+
+ <p>A source release generally includes an image of CVS repository. Files excluded
+ include any proposals/ or whiteboard/ code and the www/ directory. The source
+ release will often include generated documentation.</p>
- <p>It is common practive to split the release image to parts,
- separating documentation, source code and binary.</p>
-
<p>This directory is meaningful only to release managers. End-user
should be oblivious to it.</p>
-
</td>
<td>NO</td>
</tr>
-
-
<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/.
- </td>
+ <td></td>
<td>YES</td>
</tr>
+ <tr>
+ <td>whiteboard/ or proposals/</td>
+ <td>Revolutions and other untested code bases.</td>
+ <td>It is here where developers will host revolutions, forks and other deviations
of codebase.
+ </td>
+ <td>YES</td>
+ </tr>
+
</table>
</section>
<section name="Points to keep in mind">
-<p>It is recommended to include a <code>.cvsignore</code> file in each
+<p>It is recommended to include a <code>.cvsignore</code> file in top-level
directory under CVS control in order to avoid the distracting
"?" message output during CVS update.
</p>
@@ -287,7 +279,6 @@
for the <a href="http://jakarta.apache.org/velocity/">Velocity</a>
project, the top-most package is org.apache.velocity.
</p>
-
<p>When adding binary files to CVS, the -kb option is automatically
used for common binary types. See the
