Publishing the Continuum Site

The Continuum site, documentation and reference documentation are now published to http://continuum.apache.org/ using the ASF's svnpubsub service.

The files published to the site are all stored under the Subversion repository at http://svn.apache.org/repos/asf/continuum/site-publish/.

This mostly operates like a normal site deployment, though there are some specific customisations and special instructions for the reference library. The processes follow those described for the Maven SCM Publish Plugin for Single module projects and Multi-module projects as applicable.

Each site checks out the production site data into the site-publish directory of the current project, to avoid being cleaned as part of the build. It is ignored by svn operations, but you should ensure that the checkout is clean if you ever cancel or have a failure during a publish operation. You can check it is clean by ensuring there is no data from svn status in that directory, or by removing it and having it get checked out again.

Editing and Publishing the Main Site

The site displayed at the root of http://continuum.apache.org (where you are reading this) has its source code in Subversion at https://svn.apache.org/repos/asf/continuum/site.

To edit and publish the site, do the following:

  1. Checkout the source code from Subversion (if you follow the instructions in Building Continuum, you will already have it.
  2. Make edits and check them using mvn site or mvn site:run until satisfied.
  3. Commit your changes (making sure your working copy is completely up to date first)
  4. Publish the site:
    mvn site-deploy

This site deployment can be done at any time, and is not tied to releases.

Note that since the main site also contains the (large!) docs and ref directories in the site-publish directory, there is a special setup-checkout profile in place to get the initial checkout without those directories. This will normally be activated whenever the site-publish directory is missing - if you happen to have active profiles from your settings.xml you may need to enable it explicitly whenever you do a deployment and that checkout is missing: mvn site-deploy -Psetup-checkout

Editing and Publishing the Continuum Documentation

The documentation displayed under the subdirectories of http://continuum.apache.org/docs/ has its source code in Subversion at https://svn.apache.org/repos/asf/continuum/trunk/continuum-docs, which is part of the main project checkout.

The instructions for managing the documentation is the same as for the main site, being published from the directory using:

mvn site-deploy

However, in this case it is typically done as part of a release process - see Releasing Continuum for instructions on doing this.

The documentation remains versioned based on the release it is related to. To best manage this with svnpubsub, the site is always published into a directory docs/latest, only requiring a small number of modifications to be made. Then, as part of the release instructions, the latest directory is copied to the versioned location - for example, http://svn.apache.org/repos/asf/continuum/site-publish/docs/1.4.1.

For site:stage to apply correctly without needing a full checkout, a workaround is applied by setting the distributionManagement/site/url element to match that of the parent site. The value is then overridden with the correct value in the maven-scm-publish-plugin configuration. This avoids the Site plugin attempting to relativize links incorrectly.

Editing and Publishing the Reference Documentation

The reference documentation, including JavaDocs and source cross-reference, is displayed under the URL http://continuum.apache.org/ref. At this time, only the latest reference documents are retained. They require quite a lot of space, and historical information is of less relevance to Continuum developers or users.

To publish the latest reference documents, you need to run:

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

This will likely cause a very large commit, and should be done infrequently. Once per release is likely to be adequate.