Built by Maven

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. The guide assumes that putty on windows is used as ssh tool. First, an entry for the site must be created in maven's setting.xml, e.g.: 

    <server>
      <id>apache.db.torque.site</id>
      <username>tfischer</username>
      <filePermissions>664</filePermissions>
      <directoryPermissions>775</directoryPermissions>
      <configuration>
        <sshExecutable>C:/Programme/PuTTY/plink</sshExecutable>
        <scpExecutable>C:/Programme/PuTTY/pscp</scpExecutable>
      </configuration>
    </server>

Then an appropriate private key must be created using puttygen. Save the key at a safe place locally, and paste the public key to the ~/.ssh/authorized_keys2 file relative to your home directory on people.apache.org.

Now you can begin to build and deploy the site:

  • run "mvn clean post-site" in the torque-parent module.
  • check the site in torque-site/target/site
  • Start putty's pageant.
  • Load the private key you have generated previously into pageant.
  • It might be a good idea to create a tar.gz backup of the current state of the site in your apache home directory, in case anything goes wrong.
  • run mvn site:deploy in the torque-site module. This should trigger mvn scm-publish:publish-scm.
  • 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.

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.