CVS Repository Standards
The following document describes the Giant Java Tree
"Developer Requirements". In order to include your sources
on the GJT, you must meet the following requirements. If you
believe this would be a problem for you, and believe there is
a way that you can be accomodated by a simple change,
please notify me
so we can discuss possibilities.
Please be sure to
review the issue over package layout and package builds.
All packages must be self-contained.
Files will not be allowed to be checked in at any of the
top two levels of the tree. In other words, you will not
be allowed to checkin files at the 'com' or 'org' level,
nor any of the immediate levels below them.
The reason for this is simple. It is the only way to avoid
Experience has shown that if you start with this assumption,
and make a little effort, that this requirement is not too
Frankly, the only thing that is important on the GJT is that
your package compiles, so that it is re-usable by other
developers. It is not the intention of the GJT project to
be in the business of packaging software, although we do
provide some very rudimentary build facilities for those
packages that can fit the format.
Javadoc documentation is not to be checked in.
The GJT will provide a number of tools for the automatic
generation of documentation via javadoc. When a package
is automatically built for distribution, the javadoc
will also be automatically generated and included. The
javadoc documentation can be automatically generated
and downloaded via a web page for any tagged release.
JAR files are not to be checked in.
Again, JAR files will be managed automatically. With CVS,
you do not need to version control generated files, you
simply regenerate them when you need them.
The release management system will have a setup similar
to 'man', where a cache of JAR files will be maintained
to reduce overhead. When a JAR file is generated, it will
be cached in a parallel file system tree, and will be
cached for a period of time. Thus, once a JAR file is
generated, you will not have to wait for the generation
the next time you reference it.
There are still going to be cases where packages appear
to depend on some external (not generated) JAR file. The
build package will have a facility to acommodate this
via "external dependencies".
CVS Release Tags
You should tag ONLY your packages. Even if you depend on
another developer's package, you are not to apply your
tags to that package. You will include a dependency
specification with your project which indicates what
other packages it depends on, and the release tags of
those packages. This will prevent developers from
"stepping" on each other's tags.
Tags may consist only of alphanumeric characters and
the 'dash' character ('-').
You may use any scheme you wish for your release tags,
with one exception. No release tags are to begin with
"gjt-". The GJT project may use tags over the entire
tree. To avoid any potential conflict, all GJT tags
will being with the prefix "gjt-".
If you do not have a release tagging algorithm, may
Thus, if you released "4.7.2" of your package, you would
use the tag "release-4-7-2". NOTE that CVS does not allow
periods in tag names. If you released "5.1", you would use
the tag "release-5-1". If you wish to tag beta releases,
you would tag the "4.1b" release as "beta-4-1".
Special files will be recognized at the package level.
If you look at the com.ice tree, you will see that every
package stands alone, even though there are inter-dependencies.
This is essential for a giant java tree to exist.
In each package several files and directories will be
recognized as having special meaning. This allows us to
automate a great deal of the work without using Makefiles
Why? It is not clear, yet, what direction Sun is taking with
their own source management tools. It is desirable to keep
the GJT dirt simple until we can more clearly determine what
is the best approach for supporting package building. It is
the classic "wait and see" approach.
The following section is ONLY a PROPOSAL. It appears so far
that everyone's package (except mpEdit) will work
with this specification. If you have input and or
any objections, SPEAK UP NOW!
An alternative that has been
suggested is to provide an extremely simply scripting
ability with a script file at the package level. This
would allow the developer to specify 'copy' and 'move'
commands to re-arrange the distribution package at
build time. Please, provide feedback.
The current list of special files is as follows:
- doc (directory)
If this directory exists in your package directory,
it is considered to contain all of the appropriate
documentation for your package. When your package
is "constructed" for distribution, this directory
will be copied (or moved) to the top level of the
distribution package. You should include files such
as installation instructions, manifest, technical
Do NOT include JavaDoc files here.
- doc/readme* (file)
If this file exists in your package directory, it
will be copied (or moved) to the top leve of the
distribution package. The file name compare is
case insensitive, so it will also match 'readme'.
Furthermore, the files 'readme.*', will also match,
so files named 'readme.html' and 'readme.txt' will
also be copied.
The preferred arrangement is that you provide a file
'readme.html' in your pacakge. This will be copied
to the top level by the autobuilder. This file should
- doc/manual (directory)
If this directory exists in your doc directory, it
is considered to contain the "user manual" for your
package. The reason that this is separated out from
the doc directory is so that we can delineate online
"manuals", which are for "users", as opposed to
"documentation", which applies to the package.
You MUST have a file named "index.html" in this
directory which is what will be linked as the entry
point of the user manual.
Some example layouts are provided to help visualize the structure.
That is it. I hope that this does not seem too draconian. :)
The structure is designed to give us the most flexibility and power,
without forcing developers to completely change the way they do
their work or mountains of existing code.
If you use Makefiles to build your package, you can continue
to do so, since the package that you build for distribution
is not at all the same as the package that is built automatically.
The package that is built automatically is designed for developers,
not for end users. You continue to cater to the end user, unless
you wish to have it done automatically for you.
With the above simple setup, we will be able to build virtually
any combination of a package over its entire history.
If you are still convinced that you can not fit your existing layout
into the above structure FEAR NOT. We would still like to incorporate
your Java sources, even if we can not build your distribution package.
You see, it is not the goal of the GJT project to take over developers'
distribution services. The goal is to promote the re-use of code! Thus,
we would love to have your package sources on the tree, even if we can
not build your distribution package. The builder will still be able to
build a package that is ready for reuse by any developer, including source
code, javadoc documentation, and readme files.
We have a pointer to your homepage and prefer that _you_ present your work,
unless of course you do not have that luxury, which is why we attempt to
build projects that can fit into this simple paradigm.
As the GJT project matures, and it is more clear what path to take for
the automatic building of distribution packages, we hope to be able to
accommodate more complex packages.