Apache Commons logo

Introduction

THIS DESCRIPTION IS IN A STATE OF FLUX due to CMS deprecation and related changes

Commons sites use a solution based on both BuildBot (for the main site) and svnpubsub publication based on the maven-scm-publish-plugin for the component sites.

Main site

The main site content is now located in svn: https://svn.apache.org/repos/asf/commons/cms-site/trunk/ .
Site files are located under context/xdocs. You can test your changes locally using:

mvn clean site
This will generate output under target/site.

After you commit, and buildbot handles the site generation, with the output published to the staging site. Once satisfied, you can publish via the CMS site. THIS OPTION MAY SOON DISAPPEAR

A (temporary?) solution that doesn't require buildbot is to run commons-site-build.sh inside the cms-site directory which will build the site and prepare everything for you to publish the changes to the staging area.

If the publish part of the CMS doesn't work, there is a commons-site-publish.sh script that can be used to publish the current content of the staging area.

Components

Components do not use Buildbot. Instead component sites need to be built locally and checked in to SVN. The generated site is checked in to:

  • proper: https://svn.apache.org/repos/infra/websites/production/commons/content/proper/
  • sandbox: https://svn.apache.org/repos/infra/websites/production/commons/content/sandbox/
  • dormant: https://svn.apache.org/repos/infra/websites/production/commons/content/dormant/

Components must use parent 28 (sandbox parent: 10) or later.

The maven-scm-publish plugin can be used to automatically upload the generated site.

Maven will create a working copy of the site svn directory (~/commons-sites/ by default) publish your site to it and commit the changes. It will not prompt you for your svn password so the commit will fail unless subversion is configured to store your password. If it fails, you can commit the changes manually.

In order to publish the site of a single module project use

      mvn clean site-deploy

and for a multi modules project use

      mvn clean site site:stage scm-publish:publish-scm

The site can also be built locally and checked into the appropriate location manually.

Configuration

Default deployment targets are:

  • propers: https://svn.apache.org/repos/infra/websites/production/commons/content/proper/${project.artifactId}
  • sandbox: https://svn.apache.org/repos/infra/websites/production/commons/content/sandbox/${project.artifactId}
  • dormant: https://svn.apache.org/repos/infra/websites/production/commons/content/dormant/${project.artifactId}

The maven-scm-publish-plugin will delete any content not generated by the Maven site plugin. To avoid deletion of previous apis javadocs or other static content, the pom needs some configuration:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-scm-publish-plugin</artifactId>
  <configuration>
    <ignorePathsToDelete>
      <ignorePathToDelete>javadocs</ignorePathToDelete>
      <!-- other paths to ignore -->
    </ignorePathsToDelete>
  </configuration>
</plugin>

All declared paths won't be deleted from svn but rather have to be imported manually.