Maven 3.x Compatibility Notes

This document is intended for end users of Apache Maven that look into upgrading from version 2.x to 3.x and provides an overview of potential effects on existing builds.

General Changes

profiles.xml

The support for profiles outside of the POM or the settings.xml has been removed in version 3.x and users that previously used this feature are advised to move the affected profiles into their settings.xml.

Non-unique Snapshot Deployments

The setting <uniqueVersion>false</uniqueVersion> for a distribution repository has no effect in version 3.x, snapshot artifacts will always be deployed using a timestamped version.

Site and Reporting

A major aim of the refactoring in Maven 3.x 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. As a result, the 2.x versions of the Maven Site Plugin will no longer work with Maven 3. Development of an updated version of the Maven Site Plugin has already been started. See Maven 3.x and Site Plugin for further information.

In the same context, the default execution of site:attach-descriptor has been removed from the built-in lifecycle bindings for projects with packaging "pom". 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>
        <version>2.0.1</version>
        <executions>
          <execution>
            <id>attach-descriptor</id>
            <goals>
              <goal>attach-descriptor</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...

Last but not least, plugin configuration in the <reporting> section no longer affects plugins in the <build> section of the POM. Users that employed this style of configuration will need to copy the desired configuration parameters for a plugin from the <reporting> section to the <build> section. When Maven 3 executes a plugin during the build lifecycle or directly from the command line, only plugin configuration from the <build> section is considered.

Legacy-style Repositories

Maven 3.x no longer supports repositories using <layout>legacy</layout>. Users that need to access repositories created with Maven 1.x are advised to use a repository manager that is capable of providing a Maven 2.x compatible view of the legacy repository.

Automatic Plugin Version Resolution

When a plugin was invoked without an explicit version given in the POM or on the command line, Maven 2.x used to pick the latest version available where the latest version could either be a release or a snapshot. For the sake of stability, Maven 3.x prefers the latest release version over the latest snapshot version.

Given the threat of non-reproducible builds imposed by automatic plugin version resolution, this feature is scheduled for removal as far as plugin declarations in the POM are concerned. Users of Maven 3.x will find it output a warning when missing plugin versions are detected to encourage the addition of plugin versions to the POM or one of its parent POMs. The Enforcer rule requirePluginVersions can be used additionally check for missing plugin versions in the POM.

Plugin Metaversion Resolution

Internally, Maven 2.x used the special version markers RELEASE and LATEST to support automatic plugin version resolution. These metaversions were also recognized in the <version> element for a <plugin> declaration. For the sake of reproducible builds, Maven 3.x no longer supports usage of these metaversions in the POM. As a result, users will need to replace occurrences of these metaversions with a concrete version.

Plugin Repositories

Maven 3 aims at supporting a stricter separation between the compile/runtime/test dependencies of a project and the plugins used to build the project. For this reason, both plugins and build extensions are no longer resolved from <repositories> but only from <pluginRepositories>.

For clarity, this rule only applies to the resolution of the root artifact. In other words, while a plugin is only resolved from a <pluginRepository>, the dependencies of the plugin are resolved from the original <pluginRepository> and any <repositories> specified in the plugin's POM.

Legacy-style Reactor Mode using Includes/Excludes

Maven 3 dropped support for the command-line parameter --reactor to build sub projects selected by glob patterns. Future development will focus on improvements to the make-like reactor mode that provides similar functionality but is aware of the project hierarchy.

Stricter POM Validation

The validation of the POM has been extended in Maven 3.x and will report more errors than Maven 2.x. Potentially common problems are the duplicate declaration of project dependencies or bad scopes for plugin dependencies.

Parent POM Resolution

Maven 3 no longer resolves parent POMs from the local project checkout unless the <relativePath> element is properly specified in the child POM. This improves consistency regarding the build result when building the child project in isolation and when peforming a reactor build that includes the parent project. In Maven 2, building the child project in isolation could fail while the reactor build would succeed to resolve the parent.

Extension Loading

In Maven 2.x, build extensions defined by one module had global effects and as such affected other modules in the reactor. In contrast, Maven 3 keeps the visibility of build extensions limited to the modules that actually declare them. As a consequence, modules that require build extensions, e.g. to properly resolve dependencies with custom types, and did not declare the extension but relied on some previous module in the reactor to load and share the extension will now fail to build. This is consistent with the build result one would experience when trying to build such a module on its own outside of a reactor build.

Transport Protocols (Wagons)

Unlike Maven 2, Maven 3 supports out of the box only http:, https: and file: as transport protocols. To use other transport protocols like scp:, the appropriate wagons have to be explicitly declared in the POM as a build extension. If the wagon in question is only used for deployment, it can alternatively be declared as a dependency of the Maven Deploy Plugin.

Plugin Compatibility Matrix

The table below indicates which plugins are affected by the API changes in Maven 3.x and might not function properly. Please note that the table is not complete, e.g. not all versions of a particular plugin were tested but usually only the latest release version. Also, these results were derived from the integration tests of the plugins, features of the plugin that are not covered by tests are of unknown status.

Symbol Legend:
No known incompatibilities
Some incompatibilities
Incompatible
Not tested

Plugins Maintained by the Apache Maven Community

Plugins Maintained by the Mojo Community

Plugin	Version	Status	Comments
ANTLR-3 Maven Plugin	1.0
Application Assembler Maven Plugin	1.0
APT Maven Plugin	1.0-alpha-3		Plugin versions before 1.0-alpha-3 employ a hack for embedded invocation of APT which no longer works with the class loader hierarchy in Maven 3 (MOJO-1458). Users that can't update to a newer version of the plugin can use the configuration <fork>true</fork> to workaround the issue.
Axis Tools Maven Plugin	1.3
Build Number Maven Plugin	1.0-beta-3
Failsafe Maven Plugin	2.4.3-alpha-1
Findbugs Maven Plugin	2.3		Plugin versions before 2.3 are coded against implementation classes rather than interfaces but the underlying implementation of the API has changed in Maven 3 which causes linkage errors (MFINDBUGS-100).
GWT Maven Plugin	1.2		Plugin versions before 1.2 use internal types that are no longer present to locate sources for projects in a reactor build.
Hibernate3 Maven Plugin	2.2
JavaCC Maven Plugin	2.5
JavaNCSS Maven Plugin	2.0
JBoss Packaging Maven Plugin	2.1
JSPC Maven Plugin	2.0-alpha-3
OpenJPA Maven Plugin	1.0
Selenium Maven Plugin	1.0		This plugin depends on the GMaven runtime which is not compatible with the updated IoC container in Maven 3.
Tomcat Maven Plugin	1.0-beta-1
Versions Maven Plugin	1.0
XDoclet Maven Plugin	1.0
Sonar Maven Plugin	1.0-beta-1		http://jira.codehaus.org/browse/SONAR-1265

Plugins Maintained by Third Parties