Introduction ------------ There has been lots of discussion about build processes and documentation lately, both on this list and on jakarta-general. Now that the discussion has quieted down a bit, we can think about making a decision on how to go forward.
Contents -------- I start with an analysis of our needs as I see them, then an overview of the two options I see, looking into how they satisfy these needs. This leads to several proposals. Motivation ---------- Our current documentation build process is a pain in the *** to use. Cocoon is a little bit of overkill. It takes about 30 minutes on my machine to generate all our docs. This needs to change. It would also be nice to add some auto-generated documentation to our website (jdepend, javasrc, etc). The new tools handle some of this now, and will handle more of it as they mature. 'Standards' concern ------------------- It would be somewhat annoying to adopt one option now, then find it has all but died in a few months time because it lost out to a competing tool, if this would mean a lot of work to move from one tool to the other. Discussion with and between developers of these options leads me to believe this will solve itself in the end. Especially since Sam Ruby has taken an interest... Smooth migration concern ------------------------ We have an extensive, and in some cases also quite complex build system in place, that we should not break. Fortunately, use of ant and antcall means this is easy enough to do. Stability concern ----------------- All options available to us are currently still in a beta stage, and developing fast. Fortunately, it is unlikely that the changes to the various tools will result in extensive changes to the client API, ie we will likely be able to just drop in the replacement tool and it will work with little effort. Dog food concern ---------------- We currently use cocoon, which is built on top of several avalon components. It would be nice to keep using cocoon as it means we show the world we like our own dog food. Features concern ---------------- We don't want to loose any of our current documentation features. It would be especially cumbersome if we would have to modify our xdocs directories. New features would also be cool. Ease-of-use concern ------------------- We currently include a forked ant in the jakarta-avalon cvs module because it makes it a little easier for users to get started (they don't have to install ant first). We should either include the new tools in jakarta-avalon cvs as well (to keep everything just as easy to use), or we need to accept the extra installation chores for people getting started with our project. Option: maven ------------- standard: maven is not any kind of standard yet. Some people (mainly Jon Stevens) believe it will be the new standard for jakarta site generation in the future. migration: maven is isolated from the rest of the build process through the use of external ant build files. stability: maven is in third beta and its API will probably not change very much. dog food: maven does not provide support for cocoon. features: maven does not provide support for having the xdocs <title> tag somewhere in the body of the page by default. It also does not provide support for our chosen skin atm. new features: project info generation, dependency information (on a .jar level), look-and-feel similar to Scarab (which will replace BugZilla sometime in the future), junit reports, jdepend reports, checkstyle reports, javadocs, src xref (javasrc) ease of use: maven does not promote inclusion in CVS, though it should be possible. Option: Centipede w/ Forrest ---------------------------- standard: Forrest will be the standard for the xml project site. It uses XSLT, also a standard. migration: centipede is isolated from the rest of the build process through the use of external ant build files. stability: centipede is in its first beta. The most important part of its API that we see is borrowed from Forrest, and thus Cocoon, which we already use. dog food: Centipede & Forrest make use of cocoon. features: no problems. new features: all maven's features through a maven module, jdepend, junit reports, javasrc, pluggable look and feel, pluggable modules (support for UML generation etc will be added) ease of use: Centipede and Forrest can be included in CVS like the current tools we use. Quality of Analysis ------------------- This analysis is based on browsing of the maven and centipede project websites, following of discussion of these tools, and limited use of both projects. There are probably quite a few flaws in it. I think it will suffice for making a decision, though. Previous decisions ------------------ Note that we have previously already agreed that we will use Centipede (Forrest, really) to handle the transformation of our xdocs into html. It is likely that this choice will also trickle through to the rest of the build process, though. That is why I think it neccessary to mention all this again, so all committers can evaluate the impact of this decision. Proposals --------- - Put the latest Centipede beta (which includes useful stuff like Forrest) in jakarta-avalon cvs, and start generation of our website using it. - Add new features to the website (jdepend, junit, etc) offered by Centipede incrementally. - Slowly migrate parts of our build process to be managed by Centipede, where this is possible. References ---------- Centipede - http://www.krysalis.org/centipede/ Maven - http://jakarta.turbine.org/turbine/maven Forrest - http://marc.theaimsgroup.com/?l=forrest-dev&r=1&w=2 Cocoon - http://xml.apache.org/cocoon Gump - http://jakarta.apache.org/gump/ regards, - Leo -- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
