------
 Deploy Maven Main Website
 ------
 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 the main Maven {{{http://maven.apache.org}http://maven.apache.org}} website.

 See {{{./index.html}Maven website introduction}} for instructions on the whole website publication.


Overview

 Since December 2012, the overall website uses svnpubsub mechanism and the main website uses Apache CMS:

[main-website.png] Main website mechanisms overview


How main website publication works

 Maven main website ({{http://maven.apache.org}}) is generated with {{{/plugins/maven-site-plugin}maven-site-plugin}} from a source tree
 stored in svn: {{https://svn.apache.org/repos/asf/maven/site/trunk}}.


* Edit source content

 You can edit source content in 2 ways:

   [[1]] use {{{https://cms.apache.org/maven/}the CMS UI}} through your web browser: 

     * Go to {{https://cms.apache.org/maven/}}.

     * Click link "Get Maven Working Copy".

     * Navigate to the content you want to modify.

     * Once you have modified the content, commit with the button "Submit".

     []

   [[2]] checkout the source content locally, modify it with your favorite text editor, eventually test the result (<<<mvn site>>>), then check-in source modifications.

   []

 After source tree is modified in svn, {{{http://ci.apache.org/builders/maven-site-staging}a Buildbot job}} is triggered: 

   [[1]] it builds the HTML site using {{{/plugins/maven-site-plugin}maven-site-plugin}}: <<<mvn site>>>,

   [[2]] it publishes generated HTML content to {{{https://svn.apache.org/repos/infra/websites/staging/maven/trunk/content/}CMS staging svn area}},

   [[3]] svnpubsub mecanism transfers svn CMS staging content to live CMS staging site: {{http://maven.staging.apache.org}},

   []


* Publish site content

 If everything is good, <<publish modifications>> using {{{https://cms.apache.org/maven/publish}CMS publish}} action.

 Under the hood:

   [[1]] CMS copies CMS staging svn area content to {{{https://svn.apache.org/repos/infra/websites/production/maven/content/}website production svn area}},

   [[2]] as previous operation will delete content not built from website source (mainly component reference documentation),
   CMS re-adds content identified in {{{http://maven.apache.org/extpaths.txt}<<<extpaths.txt>>>}},

   [[3]] svnpubsub mecanism transfers svn production content to live production site: {{http://maven.apache.org}}.

 []


How Doxia website publication works

 Doxia uses the exact same mecanisms:

 * you can edit {{{https://svn.apache.org/repos/asf/maven/doxia/site/trunk}svn source tree}} either locally or
 through {{{https://cms.apache.org/maven-doxia/}CMS UI}},

 * {{{http://ci.apache.org/builders/maven-doxia-site-staging}a Buildbot job}} builds the site and updates 
 {{{https://svn.apache.org/repos/infra/websites/staging/maven-doxia/trunk/content/}website staging svn area}},

 * svnpubsub published to {{{http://maven-doxia.staging.apache.org}live staging site}},

 * if everything is good, <<publish modifications>> using {{{https://cms.apache.org/maven-doxia/publish}CMS publish}} action,

 * CMS copies CMS staging svn area content to {{{https://svn.apache.org/repos/infra/websites/production/maven-doxia/content/}website production svn area}},

 * svnpubsub mecanism transfers svn production content to live production site: {{http://maven.apache.org/doxia}},
 with its {{{http://maven.apache.org/doxia/extpaths.txt}<<<extpaths.txt>>>}}

 []