ceki 01/03/20 11:48:59
Modified: xdocs/site dirlayout.xml
docs/site dirlayout.html
Log:
Compiled the remarks made on the general ML accoding to my understanding.
Your comments/objections are welcome.
Revision Changes Path
1.6 +123 -40 jakarta-site2/xdocs/site/dirlayout.xml
Index: dirlayout.xml
===================================================================
RCS file: /home/cvs/jakarta-site2/xdocs/site/dirlayout.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- dirlayout.xml 2001/03/14 23:22:40 1.5
+++ dirlayout.xml 2001/03/20 19:48:43 1.6
@@ -14,17 +14,25 @@
Having a common directory layout would allow for users familiar with
one Jakarta project to immediately feel at home in another Jakarta
project. The advantages are analogous to adopting a site-wide
-look-and-feel as jakarta-wide procedures strengthen the Jakarta brand.
+look-and-feel. Common Jakarta procedures strengthen the Jakarta brand.
</p>
<p>
-The directory structure proposed below is not binding. We recognize
-that the cost of changing an existing directory structure can be
-high. However, we expect all projects to eventually move to the
-proposed layout assuming that the migration can be accomplished with
-reasonable effort. <b>The layout is subject to approval.</b>
+The directory structure proposed here is based on best-practices as
+suggested by Jakarta committers. We recognize that the cost of
+changing an existing directory structure can be high. As such, this
+proposal is not binding.
</p>
+<p>Unless specified otherwise, the term project refers to a
+sub-project of the Jakarta project. The terms sub-project and project
+are used interchangeably and the intended meaning should be clear from
+the context.</p>
+
+<p>
+<b>This proposal is subject to approval.</b>
+</p>
+
</section>
<section name="Common Directory Layout">
@@ -53,20 +61,20 @@
<td>src/</td>
<td>Source code.</td>
- <td>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. If the source
- is the Java language, then it should follow a package structure that is
- defined like this: org.apache.PROJECT. For example, for
- the <a href="http://jakarta.apache.org/velocity/">Velocity</a> project, it is
- org.apache.velocity.
+ <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>
+
</td>
<td>YES</td>
</tr>
+
<tr>
- <td>xdocs/</td>
- <td>Documentation file in XML format.</td>
+ <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
@@ -76,6 +84,7 @@
<td>YES</td>
</tr>
+
<tr>
<td>docs/</td>
<td>Documentation files intended for the end user.</td>
@@ -83,10 +92,11 @@
<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 xdocs directory and then
- "transformed" into this directory. It is then checked into CVS and
- checked out of CVS on the live website. This can serve a dual purpose
- of being the documentation for a project as well as the website.
+ 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.
</td>
<td>YES</td>
</tr>
@@ -155,61 +165,134 @@
<tr>
<td>build/lib/</td>
- <td>Binary jar files required in building the sub-project.</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 -kb option is automatically
- added when placing common binary types under CVS control. See the
- <code>CVSROOT/cvswrappers</code> file for the exact types. Note, it
- is allowable to place the .jar files at the top level /lib directory.
+ 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
+ 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>
+
</td>
<td>YES</td>
</tr>
<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>This directory contains most of the binaries related with the
+ sub-project, generated or not.</td>
+
+ <td>The contents of the dist/ directory should be enough to use the
+ project.
</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>Other binary files such as icons and images should also be placed
- under dist/classes/. In other words, when the project is built, the
- output directory should be this directory.
+ <p>Note that including raw classes in a distribution will waste
+ network bandwidth as well as disk space.</p>
</td>
<td>NO</td>
</tr>
+
<tr>
- <td>contribs/</td>
- <td>Contributions not officially part of the sub-project.</td>
+ <td>dist/release/</td>
+
+ <td>This directory contains the project release binaries in .tar.gz
+ and .zip format.</td>
- <td>Some projects use other names such as whiteboard/ or proposals/.
+ <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>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>YES</td>
+ <td>NO</td>
</tr>
+
+
<tr>
- <td>lib/</td>
- <td>.jar or other library files that the project depends on.</td>
+ <td>contribs/</td>
+ <td>Contributions not officially part of the sub-project.</td>
- <td>This directory and the build/lib/ directories
- are used to store library files that the project depends on. It is
- allowable to choose to store files in one or both directories.
+ <td>Some projects use other names such as whiteboard/ or proposals/.
</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
+directory under CVS control in order to avoid the distracting
+"?" message output during CVS update.
+</p>
+
+<p>If the source is in the Java language, then the package hierrarchy
+ for a given project should start at org.apache.PROJECT. For example,
+ 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
+ <code>CVSROOT/cvswrappers</code> file for the exact types.
+</p>
</section>
1.9 +140 -40 jakarta-site2/docs/site/dirlayout.html
Index: dirlayout.html
===================================================================
RCS file: /home/cvs/jakarta-site2/docs/site/dirlayout.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- dirlayout.html 2001/03/15 11:20:18 1.8
+++ dirlayout.html 2001/03/20 19:48:54 1.9
@@ -133,15 +133,21 @@
Having a common directory layout would allow for users familiar with
one Jakarta project to immediately feel at home in another Jakarta
project. The advantages are analogous to adopting a site-wide
-look-and-feel as jakarta-wide procedures strengthen the Jakarta brand.
+look-and-feel. Common Jakarta procedures strengthen the Jakarta brand.
</p>
<p>
-The directory structure proposed below is not binding. We recognize
-that the cost of changing an existing directory structure can be
-high. However, we expect all projects to eventually move to the
-proposed layout assuming that the migration can be accomplished with
-reasonable effort. <b>The layout is subject to approval.</b>
+The directory structure proposed here is based on best-practices as
+suggested by Jakarta committers. We recognize that the cost of
+changing an existing directory structure can be high. As such, this
+proposal is not binding.
</p>
+ <p>Unless specified otherwise, the
term project refers to a
+sub-project of the Jakarta project. The terms sub-project and project
+are used interchangeably and the intended meaning should be clear from
+the context.</p>
+ <p>
+<b>This proposal is subject to approval.</b>
+</p>
</blockquote>
</td></tr>
</table>
@@ -213,13 +219,12 @@
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- 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. If the source
- is the Java language, then it should follow a package structure that is
- defined like this: org.apache.PROJECT. For example, for
- the <a href="http://jakarta.apache.org/velocity/">Velocity</a> project, it is
- org.apache.velocity.
+ <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>
+
</font>
</td>
@@ -232,12 +237,12 @@
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- xdocs/
+ src/xdocs/
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- Documentation file in XML format.
+ Documentation files in XML format.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
@@ -270,10 +275,11 @@
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 xdocs directory and then
- "transformed" into this directory. It is then checked into CVS and
- checked out of CVS on the live website. This can serve a dual purpose
- of being the documentation for a project as well as the website.
+ 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.
</font>
</td>
@@ -421,16 +427,20 @@
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- Binary jar files required in building the sub-project.
+ Binary jar files required for building the sub-project.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The jar files are added to the classpath by the bootstrapping
- shell scripts before invoking ANT. The -kb option is automatically
- added when placing common binary types under CVS control. See the
- <code>CVSROOT/cvswrappers</code> file for the exact types. Note, it
- is allowable to place the .jar files at the top level /lib directory.
+ 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
+ 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>
+
</font>
</td>
@@ -448,14 +458,14 @@
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- Generated jar files and other sub-project binaries.
+ This directory contains most of the binaries related with the
+ sub-project, generated or not.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- This directory contains jar files for the
- sub-project. Distribution binaries in .tar.gz and .zip formats should
- also be placed in this directory.
+ The contents of the dist/ directory should be enough to use the
+ project.
</font>
</td>
@@ -468,6 +478,54 @@
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
+ dist/bin/
+ </font>
+</td>
+ <td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
+ <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+ Scripts and executables that the end-user will invoke to run the
+ project.
+ </font>
+</td>
+ <td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
+ <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+ A one-stop location to run the project as an application.
+ </font>
+</td>
+ <td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
+ <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+ NO
+ </font>
+</td>
+ </tr>
+ <tr>
+ <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
+ <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+ dist/lib/
+ </font>
+</td>
+ <td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
+ <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+ .jar or other library files that the project
+ depends on during runtime.
+ </font>
+</td>
+ <td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
+ <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+ This directory and the build/lib/ directories are used to store
+ library files that the project depends on at runtime.
+
+ </font>
+</td>
+ <td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
+ <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+ YES
+ </font>
+</td>
+ </tr>
+ <tr>
+ <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
+ <font color="#000000" size="-1" face="arial,helvetica,sanserif">
dist/classes/
</font>
</td>
@@ -479,9 +537,15 @@
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- Other binary files such as icons and images should also be placed
- under dist/classes/. In other words, when the project is built, the
- output directory should be this directory.
+ <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>
+
+ <p>Note that including raw classes in a distribution will waste
+ network bandwidth as well as disk space.</p>
</font>
</td>
@@ -494,42 +558,54 @@
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- contribs/
+ dist/release/
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- Contributions not officially part of the sub-project.
+ This directory contains the project release binaries in .tar.gz
+ and .zip format.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- Some projects use other names such as whiteboard/ or proposals/.
+
+ <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>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>
+
+
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- YES
+ NO
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- lib/
+ contribs/
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- .jar or other library files that the project depends on.
+ Contributions not officially part of the sub-project.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- This directory and the build/lib/ directories
- are used to store library files that the project depends on. It is
- allowable to choose to store files in one or both directories.
+ Some projects use other names such as whiteboard/ or proposals/.
</font>
</td>
@@ -540,6 +616,30 @@
</td>
</tr>
</table>
+ </blockquote>
+ </td></tr>
+ </table>
+ <table border="0" cellspacing="0"
cellpadding="2" width="100%">
+ <tr><td bgcolor="#525D76">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <strong>Points to keep in mind</strong>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+ <p>It is recommended to include a
<code>.cvsignore</code> file in each
+directory under CVS control in order to avoid the distracting
+"?" message output during CVS update.
+</p>
+ <p>If the source is in the Java
language, then the package hierrarchy
+ for a given project should start at org.apache.PROJECT. For example,
+ 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
+ <code>CVSROOT/cvswrappers</code> file for the exact types.
+</p>
</blockquote>
</td></tr>
</table>
