Torque – Editing and Deploying the Torque site

Introduction

This document is addressed to Torque committers who wish to edit and deploy the Torque site. If you find anything missing or wrong, please edit this document. If you find any procedure unsatisfactory, change it and document it here :-).

Site source code and build process

The complete Torque site resides in the module torque-site. Only the reports from the subprojects are pulled into the main site via a process documented below. The subprojects do not have an own xdoc subdirectory.

For a local build of the site, cd into the torque parent dir and run mvn post-site (if you just run mvn site, the reports from the other modules will not be pulled in). When finished, the site can be found in torque-site/target/site.

Transferring the module reports to the main site

The project reports of the subprojects are pulled into the main site during the site lifecycle of the main site. This happens in the following automated steps, which are defined in the pom.xml of the torque-site module:

In the pre-site phase, the reports are copied from the site directories of the respective modules to the target directory of the site module (directories generator-site, runtime-site, ...). They are renamed to xml, the doctype header is removed, and in some cases xhtml errors are fixed.
In the site phase, the copied reports are transformed by the xslt stylesheet torque-site/src/site/xslt/body-content.xsl such that only the body part remains and the "page frame" is omitted. The result is written to the directories generator-site-content, runtime-site-content...
In the post-site phase, the body parts of the report are inserted into the placeholder pages which sources can be found in torque-site/src/site/xdoc/documentation/modules/generator/reports, torque-site/src/site/xdoc/documentation/modules/runtime/reports... Some reports do not need to be transformed, e.g. the cobertura report, the javadocs and the sources xref, they are copied unchanged.

Deploying the site

This is a step-by-step guide to deploy the whole site. Follow the recommendations in Apache Infrastructure Information concerning Publishing Maven artifacts. Recent releases do not use ssh deployment anymore, but instead the scm-publishing mechanism.

Step by step

Now you can begin to build and deploy the site:

run mvn clean post-site in the torque parent (root) module.
```
        mvn clean post-site  
         
```
check the site in torque-site/target/site
It might be a good idea to create a tar.gz or zip backup of the current state of the site in your apache home directory, in case anything goes wrong. Find the current site in pom.xml: project->distributionManagement->site->url.
run mvn site:deploy in the torque-site module. This should trigger mvn scm-publish:publish-scm.
```
        mvn site:deploy  
         
```
Wait till the site is rsynced to the apache web servers (might take some hours). Alternatively, check http://www.apache.org/dev/project-site.html for a proxy setting which allows to look at the newly deployed site before the rsync happens, but this might not work under all circumstances.
Empty the cache of your browser and check everything is ok on http://db.apache.org/torque/torque-5.0/index.html
If you are satisfied with the new site and no-one complains during the next few days, delete the backup tar.gz or zip.

Updating the site for a new release

Check that all version numbers are up to date, especially in the tutorial, usage pages and on the download page.
Check that the correct internal version id is in the configuration fixVersionIds of the maven-changes-plugin in the pom of the torque-site project. The correct number can be determined by opening the torque project in jira, clicking on "versions" in the left menu, click on the appropriate version and then on "release notes" on top of the site. The version number is the number appearing last in the URL of the page.