A major aim of the refactoring in Maven 3 was to decouple the Maven core from Doxia and to allow arbitrary reporting systems to be developed. For this reason, all reporting related code has been removed from the core of Maven 3 (MNG-4162).
As a result, the 2.x versions of the Maven Site Plugin will not work with Maven 3. Using such versions of Maven Site Plugin with Maven 3 won't generate any reports from reporting plugins, only hand-written Doxia documents (apt, xdoc, ...) will be rendered.
You need to use version 3.x of the Site Plugin, in order for it to work with Maven 3.
Tests have been made on the reporting profile of the Maven parent POM which enables some reports. You will need so update some of these plugins for them to work with Maven 3. Below you will find the minimum version required for these plugins to work in Maven 3.
| Plugin | Version |
| maven-changelog-plugin | 2.1 |
| maven-changes-plugin | 2.1 |
| maven-checkstyle-plugin | 2.5 |
| maven-javadoc-plugin | 2.6.1 |
| maven-jxr-plugin | 2.1 |
| maven-plugin-plugin | 2.5.1 |
| maven-pmd-plugin | 2.4 |
| maven-project-info-reports-plugin | 2.2 |
| maven-surefire-report-plugin | 2.4.3 |
When used with Maven 3, a report plugin version can be empty (like build plugins).
The following order/strategy will be used to find/resolve a version:
Maven 2 and Maven 3 work differently when dealing with inheritance of reports: given a plugin providing multiple report goals, in Maven 2, reports configured in child pom are added to reports from parent, whereas in Maven 3 reports from child replace reports from parent.
For example, given a multi module build where the parent POM has the index report configured and the child POM has the summary report configured for maven-project-info-reports-plugin plugin:
For more info see MSITE-596.
In Maven 3, the default execution of site:attach-descriptor has been removed from the built-in lifecycle bindings for projects with pom packaging. Users that actually use those projects to provide a common site descriptor for sub modules will need to explicitly define the following goal execution to restore the intended behavior:
<build>
<plugins>
<plugin>
<artifactId>maven-site-plugin</artifactId>
<executions>
<execution>
<id>attach-descriptor</id>
<goals>
<goal>attach-descriptor</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
Starting with version 3.0, maven-site-plugin can run with both Maven 2.2.x and 3.x. The results should be exactly the same if reports are configured in the classical Maven 2 way, in the <reporting> section. If you use the new Maven 3 way of configuring reports (not recommended), in the <reportPlugins> section, it will only work with Maven 3.
The following snippet automatically activates site:attach-descriptor when run with Maven 3:
<profiles>
<profile>
<id>maven-3</id>
<activation>
<file>
<!-- This employs that the basedir expression is only recognized by Maven 3.x (see MNG-2363) -->
<exists>${basedir}</exists>
</file>
</activation>
<build>
<plugins>
<plugin>
<artifactId>maven-site-plugin</artifactId>
<executions>
<execution>
<id>attach-descriptor</id>
<goals>
<goal>attach-descriptor</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>
Note: The profile is needed to avoid duplicate install and deploy of the site descriptor when running with Maven 2.2.x due to POM default lifecycle mappings.
Before maven-site-plugin 3.0, maven-site-plugin 2.x was compatible only with Maven 2 and maven-site-plugin 3.0-betas were compatible only with Maven 3. A trick was needed to let Maven 2 use one version of the plugin and Maven 3 another version in the same pom.xml.
The following snippet automatically activates maven-site-plugin 3.x when run with Maven 3:
<profiles>
<profile>
<id>maven-3</id>
<activation>
<file>
<!-- This employs that the basedir expression is only recognized by Maven 3.x (see MNG-2363) -->
<exists>${basedir}</exists>
</file>
</activation>
<build>
<pluginManagement>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<version>3.2</version>
</plugin>
</plugins>
</pluginManagement>
<plugins>
<plugin>
<artifactId>maven-site-plugin</artifactId>
<executions>
<execution>
<id>attach-descriptor</id>
<goals>
<goal>attach-descriptor</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>
Note: Be aware that you should also use <pluginManagement> to specify the version for maven-site-plugin 2.x. If you define the plugin version directly inside the <plugins> section of the <build> element then that version is always used, no matter which version of Maven is used. That snippet would look like this:
<build>
<pluginManagement>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<version>2.3</version>
</plugin>
</plugins>
</pluginManagement>
</build>
The <reporting> section of the POM has been added to the Site Plugin's configuration in Maven 3. The content of the configuration has been kept as similar as possible to Maven 2 and the maven-reporting-exec component transforms the configuration on the fly.
Reports are configured in the <reporting> section of the POM. This stays the recommended configuration format.
<reporting>
<excludeDefaults>true</excludeDefaults>
<outputDirectory>${project.build.directory}/site</outputDirectory>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-project-info-reports-plugin</artifactId>
<version>2.4</version>
<configuration>
<dependencyDetailsEnabled>false</dependencyDetailsEnabled>
<dependencyLocationsEnabled>false</dependencyLocationsEnabled>
</configuration>
<reportSets>
<reportSet>
<reports>
<report>dependencies</report>
<report>scm</report>
</reports>
</reportSet>
</reportSets>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.8</version>
</plugin>
</plugins>
</reporting>
Reports can be configured in the configuration of maven-site-plugin as <reportPlugins> elements.
This new configuration format is not actually ready for end-users: please don't use it for the moment.
Explanation: The new format does not actually support report plugins configuration inheritance, which is crucial for usability: see MSITE-484. This format was technically necessary to remove most reporting logic from Maven 3, but a new inheritance mechanism still needs to be added to make it as flexible as the old format.
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<version>3.2</version>
<configuration>
...
<reportPlugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-project-info-reports-plugin</artifactId>
<version>2.4</version>
<configuration>
<dependencyDetailsEnabled>false</dependencyDetailsEnabled>
<dependencyLocationsEnabled>false</dependencyLocationsEnabled>
</configuration>
<!-- simpler configuration without reportSets available for usual cases -->
<reports>
<report>dependencies</report>
<report>scm</report>
</reports>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.8</version>
</plugin>
</reportPlugins>
</configuration>
</plugin>
</plugins>
</build>