 ------
 Migrate
 ------
 Dennis Lundberg
 Hervé Boutemy
 ------
 2016-04-09
 ------

 ~~ 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


Migrate

  The Site Plugin has had a couple of upgrades that requires the user to make
  adjustments to their environment, documents or configuration. Below is a list
  of these changes and what you as a user need to be aware of.

* From 3.4 to 3.5.1

  * Since {{{http://velocity.apache.org}Velocity}} has been upgraded from version 1.5 to version 1.7,
  which changes escaping rules, you may need to update escape sequences in your <<<.vm>>> documents and/or skins.
  If you can't update content and/or skin immediately, you can manually downgrade Velocity version by
  configuring a dependency to Maven Site Plugin:

+-----------------+
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-site-plugin</artifactId>
      <dependencies>
        <dependency>
          <groupId>org.apache.velocity</groupId>
          <artifactId>velocity</artifactId>
          <version>1.5</version>
        </dependency>
      </dependencies>
    </plugin>
+-----------------+

  * Site Decoration Model 1.7.0 has changed type for <<<head>>> and <<<footer>>> from <<<DOM>>> to <<<String>>>:
  if your <<<site.xml>>> (or one parent) contains XML content, you'll need to escape it, usually by
  adding <<<\<![CDATA[>>> and <<<]]\>>>> around the content:

+-----------------+
<project xmlns="http://maven.apache.org/DECORATION/1.7.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/DECORATION/1.7.0 http://maven.apache.org/xsd/decoration-1.7.0.xsd">
    <body>
        <head>
            <![CDATA[<anyHeadElement/>]]>
        </head>
        <footer>
            <![CDATA[<anyFooterElement/>]]>
        </footer>
    ...
    </body>
</project>
+-----------------+

  * Interpolation of <<<$\{project.*}>>> and <<<$\{*}>>> expressions in <<<site.xml>>> have changed to be
  consistent with equivalent feature in Maven <<<pom.xml>>>: interpolation is now done <after> inheritance.
  For <<<site.xml>>>, this may lead to failures on urls (often on <<<$\{project.url}>>> expression),
  that are expected to be rebased during inheritance: a new <early interpolation> feature has been added
  in Maven Site Plugin 3.5.1 throught <<<$\{this.*}>>> expressions (see
  {{{/doxia/doxia-sitetools/doxia-integration-tools/index.html} Doxia Integration Tools reference documentation}}).
  With this feature (for example <<<$\{this.url}>>> or <<<$\{this.customProperty}>>> expressions), you'll get
  former <<<site.xml>>> interpolation result.

  []

* From 2.x to 3.x

  * Version 3 of the plugin requires at least <<Maven 2.2.0>> to run.

  * If you use <<Maven 3>> please read the {{{./maven-3.html}Maven 3}} guide about relevant issues.

  []

* From 2.2.x to 2.3.x

  * The <<<site:stage>>> and <<<site:stage-deploy>>> goals have been decoupled from site generation.
  Executing these goals without generating the site first will lead to a build failure.

  []

* From 2.1.x to 2.2.x

  * The plugin now requires at least <<Maven 2.2.0>> to run, you cannot use it
  with older Maven versions.

  * The plugin now requires at least <<Java 5>> to run, you cannot use it
  with older Java versions.

  []

* From 2.0.x to 2.1.x

  * The plugin now requires at least <<Maven 2.1>> to run, you cannot use it
  with older Maven versions.

  * The plugin has been upgraded to use <<Doxia 1.1>>, which has seen a lot of
  major changes itself. If you experience unexpected behavior, please read these
  resources:

    * {{{/doxia/whatsnew-1.1.html}Doxia: what's new in 1.1?}}

    * {{{/doxia/references/doxia-apt.html}Doxia: Enhancements to the APT format}}

    * {{{/doxia/issues/index.html}Doxia: Issues & Gotchas}}

    * {{{/doxia/faq.html}Doxia: Frequently Asked Questions}}

    []

  []