------ Deploy Maven Component Reference Documentation ------ Barrie Treloar Hervé Boutemy ------ 2013-09-23 ------ ~~ Licensed to the Apache Software Foundation (ASF) under one ~~ or more contributor license agreements. See the NOTICE file ~~ distributed with this work for additional information ~~ regarding copyright ownership. The ASF licenses this file ~~ to you under the Apache License, Version 2.0 (the ~~ "License"); you may not use this file except in compliance ~~ with the License. You may obtain a copy of the License at ~~ ~~ http://www.apache.org/licenses/LICENSE-2.0 ~~ ~~ Unless required by applicable law or agreed to in writing, ~~ software distributed under the License is distributed on an ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY ~~ KIND, either express or implied. See the License for the ~~ specific language governing permissions and limitations ~~ under the License. ~~ NOTE: For help with the syntax of this file, see: ~~ http://maven.apache.org/doxia/references/apt-format.html Introduction This document gives step-by-step instructions for deploying Maven components reference documentation inside the Maven {{{http://maven.apache.org}http://maven.apache.org}} website. See {{{./index.html}Maven website introduction}} for instructions on the whole website publication (main site content + components). Overview Since December 2012, the overall website uses svnpubsub mechanism: [component-reference-documentation.png] Components reference documentation mechanisms overview How components reference documentation publication works Components don't use CMS: components reference documentation are versioned and generated from full sources, with both handwritten content (like Maven main site) and content generated from sources (javadoc, unit-test results, integration test results...). * Staging component reference documentation Reference documentation of a component is staged in <<>>, where <<>> is the component name and <<>> can be: * the component type, like <<>>, <<>>, <<>>, ... (see {{/shared-archives}}, {{/plugins-archives}}, {{/skins/archives}}) * the component name for standalone components, like <<>>, <<>>, <<>>, <<>>, ... (see {{/archetype-archives}}, {{/plugin-tools-archives}}, {{/surefire-archives}}, {{/wagon-archives}}) [] To publish component reference documentation: [[0]] 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 +----------+ [[1]] build the reference documentation: +----------+ mvn -Preporting site site:stage +----------+ Notice: <<>> is really necessary only for multi-modules components, but added unconditionally in these instructions to keep them as straightforward as possible. [[2]] stage the reference documentation to website production svn area, using {{{/plugins/maven-scm-publish-plugin}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 [] [] <>: to avoid published content do disappear when Maven main content is published (see {{{./deploy-maven-website.html}documentation}} for more details), check that the <<>> path is properly declared in {{{/extpaths.txt}<<>>}}. * 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 <<>> command: * Unix: +----------+ SVNPUBSUB=https://svn.apache.org/repos/infra/websites/production/maven/content 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/content 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 {{{http://svnbook.red-bean.com/en/1.8/svn.ref.svnmucc.re.html}<<>> command}}: +----------+ svnmucc -m "Publish yyy $version documentation" \ -U https://svn.apache.org/repos/infra/websites/production/maven/content \ 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 {{{/plugins/}index}}), shared (see {{{/shared/}index}}), poms (see {{{/pom/}index}}) and skins (see {{{/skins/}index}}). Update the version number and release date for the component in the <<>> page. See {{{../website/deploy-maven-website.html}Deploy Maven website}} for more in-depth instructions on main site content editing. <>: if you forget about updating the index page, dist-tool has a {{{https://builds.apache.org/view/M-R/view/Maven/job/dist-tool-plugin/site/dist-tool-check-index-page.html}report run daily}} that will gently send a failure notification on notifications@maven.a.o.