Updating the Lenya Website

Before you try to update the Lenya website, make sure you meet the following requirements:

• You have Apache Forrest installed on your machine (v 0.8-dev). This means you have your environment set up in a way that you can call forrest in any directory.
• You have enabled Apache Forrest to handle all image types natively. (see note)
• You are an active Lenya committer with write access to SVN.
• Your subversion is configured correctly (see note)

If you are not a committer but like to contribute to the documentation, you're most welcome as well. If you want to make additions or corrections to the lenya documentation/website, please keep on reading.

Instead of committing please make an svn diff of lenya.docu (see above) and contribute the patch via our bug tracker. Let us know about it on the developer's mailing list. A committer will happily pick your patch up from the bug tracker and apply it.

You will have to do this only the first time when doing the website.

• svn co https://svn.apache.org/repos/asf/lenya/docu/ lenya.docu
  
  lenya.docu->This is our documentation and website source tree. Here you will edit the site.
• svn co https://svn.apache.org/repos/asf/lenya/site/ lenya.apache.org
  
  lenya.apache.org->This is our website live tree. Here you will have to copy the build of lenya.docu.

The multiple changes files can be directly generated from the SVN commit logs with the following procedure:

• run svn log -v -r $LAST:HEAD --xml http://svn.apache.org/repos/asf/lenya > src/documentation/content/svn-log/tlp-HEAD.svn.xml in the root of the docu branch. Where $LAST is the revision number of the last commit from the last month.
• Each month somebody need to create a new log file for the last month and link it to the changes section. Do forrest run

You can find out the first and last revision (till it was updated) of the current HEAD by requesting http://localhost:8888/tlp-HEAD.svn-revision.xml numbers. If this file contains more then one month then you can request http://localhost:8888/tlp-HEAD.svn-sh.xml to generate shell commands, which you can execute in the src/documentation/content/svn-log dir (you need to edit them before execute).

The Website at http://lenya.apache.org/ is a static site, which is served from the checkout dir lenya.apache.org on the server based on http://svn.apache.org/repos/asf/lenya/site/ by an Apache httpd server.

The content of lenya.apache.org has to be generated by forrest based on the lenya.docu. This has to be done on your local machine because forrest is not installed on the server.

Copy the deloyed files to your lenya.apache.org. Commit the changes in lenya.apache.org. A cron job updates the static files in lenya.apache.org of the server every 24 hours via a simple svn up.

The typical roundtrip process to update the website has the following steps.

1) edit the documentation src -> lenya.docu

• cd $lenya.docu; svn up - change to your local checkout of the docu and update it.
• Follow "Generating changes based on svn"!
• Run forrest run locally on your machine. You can now browse the website at http://localhost:8888/.
• Edit the content using your favourite editor. Refer to the forrest documentation if necessary. Hit the Reload button in your browser and test your changes locally on your machine until they work the way you intended.

2) deploy and commit your changes to the documentation src -> lenya.docu

• Run forrest -> This will create the site in lenya.docu/build/site
  (Note that Forrest sometimes claims that the build failed, please see the broken-links.xml. Here you can find the pages that have errors and which pages refer to them.)
• Check in your changes (if you are a committer) svn ci -m "my changes message" or prepare a patch (if you aren't) svn diff > patch.txt of lenya.docu

3) copy deployed changes from the documentation src to the website checkout-> lenya.apache.org

• cd $lenya.apache.org; svn up - change to your local checkout of the website and update it.
• cp -r $lenya.docu/build/site/* . - copy the deployed site from step 2.
• Create and copy the Javadoc for both branches (build javadocs, Copy from build/webapp/site/apidocs to lenya/site/apidocs/1.2 and lenya/site/apidocs/2.0)
• Commit your changes to lenya.apache.org svn ci -m "my changes message".

If you are looking into a way to short the steps described in the Roundtrip website update, then do the following (please still test your changes first).

Do once, create $lenya.docu/deploy.svn.settings file. These credentials are needed by forrestbot so that it can do your 'svn add' and 'svn commit' etc. to the lenya/site/ repository. The deploy.svn.settings file looks like:

<?xml version="1.0"?>
<project>
    <property name="deploy.svn.user" value="myApacheUsername"/>
    <property name="deploy.svn.password" value="myPassword"/>
</project> 

Generating and publishing the main docs is very easy using a local forrestbot:

cd $lenya.docu
forrest -f publish.xml build
forrest -f publish.xml deploy

This builds the documentation locally then deploys it by committing it to the lenya/site SVN. Then a cronjob on the server will automatically publish it (see next section).

You can use a similar script we are using on the zones server in $lenya.docu.

#!/bin/bash
svn up
source SVN-HEAD-REV.txt
svn log -r $LAST:HEAD -v --xml http://svn.apache.org/repos/asf/lenya > src/documentation/content/svn-log/tlp-HEAD.svn.xml
forrest -f publish.xml build
forrest -f publish.xml deploy

There is a cron job on people which will do 'svn update' in the server lenya.apache.org dir every 24 hours (see /x1/home/thorsten/thorsten.ct). If you want to invoke the script manually then ...

ssh people.apache.org
/x1/home/thorsten/bin/lenya-update.sh

Alternatively you can do the following (this is basicly what the script does).

ssh people.apache.org
cd /www/lenya.apache.org
umask 0002
svn update