Plugins Compatibility Matrix for Maven 3

Version Resolution

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:

• search the same groupId/artifactId in the build.plugins section
• search the same groupId/artifactId in the build.pluginManagement.plugins section
• resolve with current repositories (can include automatic SNAPSHOT resolution)

Notice that Maven 3.0.x reports a misleading warning in case of empty report plugin version: see MNG-5477, fixed in Maven 3.1.0.

Site descriptor attachment

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>

Using the same version of maven-site-plugin for both Maven 2 and Maven 3

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.

Using maven-site-plugin 2.x with Maven 2 and maven-site-plugin 3.x with Maven 3

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.9.0</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>

Configuration formats

The <reporting> section of the POM has been added to the Site Plugin's configuration as <reportPlugins> 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.

<project>
...
  <reporting>
    <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>
...
</project>

[WARNING] Reporting configuration should be done in <reporting> section, not in maven-site-plugin <configuration> as reportPlugins parameter.

<project>
...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-site-plugin</artifactId>
        <version>3.2</version><!-- last maven-site-plugin version supporting this reportPlugins configuration -->
        <configuration>
          ...
          <reportPlugins><!-- not supported any more, causes WARNING in Maven 3.5.0: move to <project><reporting><plugins> instead -->
            <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>
...
</project>

Inheritance of reports for Maven 3 before 3.0.4

Maven 3 before 3.0.4 works differently from Maven 2 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 up to 3.0.3 reports from child replace reports from parent. Since 3.0.4, though, inheritance of reports works in the same way as with Maven 2.

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:

• with Maven 2 and Maven 3.0.4, the child site will have both the index and summary reports,
• with Maven 3.0.3, the child site will have only the summary report.

For more info see MSITE-596.