Staging component reference documentation

Reference documentation of a component is staged in http://maven.apache.org/xxx-archives/yyy-LATEST, where yyy is the component name and xxx can be:

• the component type, like shared, plugins, skins, ... (see /shared-archives/, /plugins-archives/, /skins/archives/)
• the component name for standalone components, like archetype, plugin-tools, surefire, wagon, ... (see /archetype-archives/, /plugin-tools-archives/, /surefire-archives/, /wagon-archives/)

To publish component reference documentation:

1. prerequisite: eventually build the component if it has not been done previously, or some reports may miss build or integration information:

   mvn -Prun-its install

2. build the reference documentation:

   mvn -Preporting site site:stage

   Notice: site:stage is really necessary only for multi-modules components, but added unconditionally in these instructions to keep them as straightforward as possible.

3. stage the reference documentation to website production svn area, using maven-scm-publish-plugin: (TODO: explanations on configuration in pom to yyy-LATEST)

   mvn scm-publish:publish-scm

   svnpubsub mechanism transfers svn production content to live production site

Notice: content is in fact published to /components/ directory, and rewrite rules in .htaccess detect files not found in main site to try /components/ content instead.

Publishing versioned component reference documentation

When doing a release, yyy-LATEST content staged in previous section needs:

1. to be archived to versioned directory before a newer revision is published into -LATEST,
2. to replace the actual component reference documentation.

This is done with operations on website production svn area, either with svn command:

• Unix:

  SVNPUBSUB=https://svn.apache.org/repos/infra/websites/production/maven/components
  
  svn cp $SVNPUBSUB/xxx-archives/yyy-LATEST $SVNPUBSUB/xxx-archives/yyy-$version -m "Archive versioned site."
  
  svn rm $SVNPUBSUB/xxx/yyy -m "Remove old site."
  svn cp $SVNPUBSUB/xxx-archives/yyy-$version $SVNPUBSUB/xxx/yyy -m "Publish new site."

• Windows:

  set SVNPUBSUB=https://svn.apache.org/repos/infra/websites/production/maven/components
  
  svn cp %SVNPUBSUB%/xxx-archives/yyy-LATEST %SVNPUBSUB%/xxx-archives/yyy-$version -m "Archive versioned site."
  
  svn rm %SVNPUBSUB%/xxx/yyy -m "Remove old site."
  svn cp %SVNPUBSUB%/xxx-archives/yyy-$version %SVNPUBSUB%/xxx/yyy -m "Publish new site."

or with svnmucc command:

svnmucc -m "Publish yyy $version documentation" \
  -U https://svn.apache.org/repos/infra/websites/production/maven/components \
  cp HEAD xxx-archives/yyy-LATEST xxx-archives/yyy-$version \
  rm xxx/yyy \
  cp HEAD xxx-archives/yyy-LATEST xxx/yyy

Updating index page in the Maven site

Some component types have an index page refering to each components of the same type. This is the case for plugins (see index), shared (see index), poms (see index) and skins (see index).

Update the version number and release date for the component in the content/apt/xxx/index.apt page.

See Deploy Maven website for more in-depth instructions on main site content editing.

Notice: if you forget about updating the index page, dist-tool has a report run daily that will gently send a failure notification on notifications@maven.a.o.