Developer
Projects
Reuse
Policy
Standards

Release Pkg

CVS Repository Standards

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 total chaos. Experience has shown that if you start with this assumption, and make a little effort, that this requirement is not too onerous. 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 we suggest:

• release-n-n-n

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 or scripts.

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.

NOTICE 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 documentation, etc.

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 then contain

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.