| Directory name |
Content |
Comment |
Under CVS Control? |
| LICENSE.txt |
A copy of the Apache License |
The LICENSE.txt should be placed at a prominent location.
This file should have the suffix .txt so that it can be opened
easily on platforms that use suffix mappings. |
YES |
| src/ |
Source code. |
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. 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/.
|
YES |
| src/xdocs/ |
Documentation files in XML format. |
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 available.
|
YES |
| docs/ |
Documentation files intended for the end user. |
The docs/ directory contain most of the documentation for the
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. Alternatively
some projects may place
|
NO |
| docs/ or www/ |
Web site documentation. |
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.
|
YES |
| www/index.html |
Starting point for browsing the documentation. |
Browsing the documentation locally should yield the same results
as browsing the documentation on the sub-project home page on the
Jakarta web site.
|
YES |
| docs/api |
API documentation as generated by the Javadoc tool. |
Placing the API documenation under docs/api/ makes it slightly
easier for other documentation files under docs/ to reference API
documentation and vice versa. It is not recommended to check this
into CVS. At some point, we will have the Alexandria project
building the documentation for all of the Jakarta Projects and making
the API documentation available that way.
|
NO |
| tools/ or build/ |
Files required for building the sub-project. |
Building includes compiling source code, generating javadoc
documentation, the creation of jar files and the distribution files
in tar.gz or zip formats.
|
YES |
| build.xml or build/build.xml |
The ANT build script. |
All Jakarta projects are required to use ANT as their build tool.
Note, it is allowable to place this file at the top level directory
structure.
|
YES |
| build.sh build.bat |
Shell scripts for Unix and DOS environments to bootstrap the ANT
build process. |
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 in subdirectory build/.
|
YES |
| tools/lib or build/lib/ |
Binary jar files required for building the sub-project. |
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.
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/.
|
YES |
| dist/ |
This directory is an image of the distribution files. Hence why it is called "dist" (short
for distribution). |
The contents of the dist/ directory should be enough to use the
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.
|
NO |
| bin/ or build/ |
Intermediate files files generated while building the project. |
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.
|
NO |
| distributions/ |
This directory contains the project release distributions. These are often
project.tar.gz, project.zip, project.rpm or project.war format. |
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.
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.
This directory is meaningful only to release managers. End-user
should be oblivious to it.
|
NO |
| contribs/ |
Contributions not officially part of the sub-project. |
|
YES |
| whiteboard/ or proposals/ |
Revolutions and other untested code bases. |
It is here where developers will host revolutions, forks and other deviations of codebase.
|
YES |
