| ------ |
| 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}} |
| |
| [] |
| |
| [] |