Understanding Maven Project Version Inheritance and Best Practices

Fundamentals of Maven Project Inheritance

In Maven project management, project inheritance serves as a crucial dependency management mechanism. When a child project declares a parent project through the <parent> element, it can inherit configuration information from the parent. However, in traditional Maven versions, the child project's POM file must explicitly specify the parent project's version number, even when both parent and child projects share the same version.

Limitations of Traditional Version Inheritance

Consider the following typical scenario: Parent project A has the following POM configuration:

<groupId>com.dummy.bla</groupId>
<artifactId>parent</artifactId>
<version>0.1-SNAPSHOT</version>
<packaging>pom</packaging>

Child project B is configured as:

<parent>
    <groupId>com.dummy.bla</groupId>
    <artifactId>parent</artifactId>
    <version>0.1-SNAPSHOT</version>     
</parent>

<groupId>com.dummy.bla.sub</groupId>
<artifactId>kid</artifactId>

In this configuration, the version number &quot;0.1-SNAPSHOT&quot; needs to be declared in two locations. If you attempt to remove <version>0.1-SNAPSHOT</version> from the child project, Maven will report an error about the missing parent version. While this design introduces configuration redundancy, it is generally reasonable since child projects automatically inherit the parent's version as their own, and the Maven Release Plugin can automatically handle version updates.

Innovative Solution in Maven 3.5.0

Starting from Maven 3.5.0, a CI-friendly version management mechanism was introduced, solving the version duplication issue through the ${revision} placeholder. The core concept of this approach is to externalize version numbers and resolve them dynamically during the build process.

Parent Project Configuration

Example configuration for the parent project's POM:

<project>
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>org.apache</groupId>
    <artifactId>apache</artifactId>
    <version>18</version>
  </parent>
  <groupId>org.apache.maven.ci</groupId>
  <artifactId>ci-parent</artifactId>
  <name>First CI Friendly</name>
  <version>${revision}</version>
  ...
  <properties>
    <revision>1.0.0-SNAPSHOT</revision>
  </properties>
  <modules>
    <module>child1</module>
    ..
  </modules>
</project>

Child Project Configuration

The child project's POM configuration is adjusted accordingly:

<project>
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>org.apache.maven.ci</groupId>
    <artifactId>ci-parent</artifactId>
    <version>${revision}</version>
  </parent>
  <groupId>org.apache.maven.ci</groupId>
  <artifactId>ci-child</artifactId>
   ...
</project>

Deployment Considerations

When using the ${revision} placeholder approach, it is essential to use the Flatten Maven Plugin to generate POM documents with specific version numbers for deployment. This plugin replaces placeholders with actual version numbers during the build process, ensuring that deployed artifacts have deterministic version information.

Alternative Approaches for Historical Versions

For versions prior to Maven 3.5.0, developers attempted combination approaches using relative paths and externalized properties:

Parent Project Configuration

<groupId>com.dummy.bla</groupId>
<artifactId>parent</artifactId>
<version>${global.version}</version>
<packaging>pom</packaging>

<properties>
   <!-- Unique entry point for version number management --> 
   <global.version>0.1-SNAPSHOT</global.version>
</properties>

Child Project Configuration

<parent>
   <groupId>com.dummy.bla</groupId>
   <artifactId>parent</artifactId>
   <version>${global.version}</version>
   <relativePath>..</relativePath>    
</parent>

<groupId>com.dummy.bla.sub</groupId>
<artifactId>kid</artifactId>

It's important to note that this approach may no longer be supported in newer Maven versions and can generate numerous warning messages during the build process.

Version Management Tool Assistance

For scenarios requiring batch version updates, the Maven Versions Plugin can be utilized:

$ mvn versions:set -DgenerateBackupPoms=false

This command parses all POM files and prompts the user to set new version numbers, making it suitable for unified version management in multi-module projects.

Conclusion and Recommendations

The Maven project version inheritance mechanism has evolved from mandatory specification to flexible configuration. For projects using Maven 3.5.0 and above, the ${revision} placeholder approach is recommended as it maintains configuration simplicity while providing flexibility in CI/CD environments. For legacy projects, appropriate version management strategies should be selected based on the specific Maven version. Regardless of the chosen approach, maintaining consistency and maintainability in version management remains crucial for project success.