Mailing-List: contact dev-help@geronimo.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@geronimo.apache.org
Received-SPF: pass (athena.apache.org: domain of jason.dillon@gmail.com
 designates 209.85.198.185 as permitted sender)
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=beta;
        h=received:mime-version:content-transfer-encoding:message-id:content-type:to:from:subject:date:x-mailer:sender;
        b=uDq8+SH5qCIBvc6K63G6BxE9moCFFPZWbMIRoLSUzi8r9FKdxUcbe1UgifXiGrQW6GdrOd4cRfJGQCV1Hc+kv6LEtyri5yAeIEnhVI9ApOf9SlJNwHvulZlDeA2WyAGH6KsQfQLLPpUioOYckNQ7TPvDecgYO9Uqp+Px8JV7sQ8=
Mime-Version: 1.0 (Apple Message framework v752.3)
Content-Transfer-Encoding: 7bit
Message-Id: <C5FC178B-0ECB-45A2-B257-81A806F91560@planet57.com>
Content-Type: text/plain; charset=US-ASCII; delsp=yes; format=flowed
To: dev@geronimo.apache.org
From: Jason Dillon <jason@planet57.com>
Subject: Some fixes for server/trunk for mvn site
Date: Sat, 8 Sep 2007 01:22:15 -0700
Sender: Jason Dillon <jason.dillon@gmail.com>

I've updated some configuration in server/trunk to allow the site to  
work with java 5 sources.

Its been, well months (or more) since I last tried building the  
site... so I'm not sure what this could break, but I'm running a site  
build now.

I think we may have to rollback to an earlier version of the site  
plugin though... cause I think the latest one might be... well  
insane... going to play with it a bit and make it work.

  * * *

On a very related note... we really should think of a nice way to  
capture per-version documentation for our projects.  This isn't  
something that Maven does for us out of the box for its site  
generation muck, but there are simple ways to get around that.

Right now we are deploying Maven-generated sites up in here:

     http://geronimo.apache.org/maven/

So, when the server's site is deployed it ends up here:

     http://geronimo.apache.org/maven/server/

What I recommend is that we put a version in there, so we can publish  
the site/javadocs/reports/whatever for 2.0 as:

     http://geronimo.apache.org/maven/server/2.0/

and 1.2:

     http://geronimo.apache.org/maven/server/1.2/

And for the latest bits we can use the snapshot name:

     http://geronimo.apache.org/maven/server/2.1-SNAPSHOT/

And then simply setup a symlink so that this goes to the same place  
(for less updates to the dev docs and such):

     http://geronimo.apache.org/maven/server/trunk/

  * * *

This is relatively simple to do and should really help out our users  
a lot....

Basically in the top-level poms instead of using this:

     <distributionManagement>
         <site>
             <id>geronimo-website</id>
             <url>scp://people.apache.org/www/geronimo.apache.org/ 
maven/server</url>
         </site>
     </distributionManagement>

We use use this:

     <distributionManagement>
         <site>
             <id>geronimo-website</id>
             <url>scp://people.apache.org/www/geronimo.apache.org/ 
maven/server/${version}</url>
         </site>
     </distributionManagement>

Maybe one day the Maven site plugins will have a better framework for  
supporting a multi-version site... like I'd like to see a <Version>  
drop-down in the top-right corner so I can select the version of the  
document I'm looking at, etc.

But, anyways... this has kinda been on my lists of things that should  
get done... just well never made it near the top.

I recommend that the PMC as well as the rest of the community  
consider making this change and implementing a general policy about  
its usage for sub-projects and hopefully define some kind of  
guidelines as to how sub-projects publish their documentation.

Developers love good docs... and they shouldn't have to dig for  
them... so, lets hand it to them on a silver plate...

--jason