In a large monorepo, a single change to one module shouldn’t force a full rebuild of the entire project. For the Lime Mojito OSS Development Standard Build, we use the gitflow-incremental-builder (GIB) Maven plugin to keep CI cycles fast, efficient, and reliable.

The GitHub gitflow-incremental-builder plugin compares your feature branch to a base branch using git to determine which maven modules require a build. The plugin also marks dependent modules so they will be rebuilt as well.

How it works in the pom.xml

The project enables incremental builds by configuring the gitflow-incremental-builder as a Maven extension. This is managed in the root pom.xml in three key areas:

1. Plugin Management: The plugin is defined in the <pluginManagement> section (version 4.6.0), ensuring version consistency across the monorepo.
2. The CI Profile: A specific ci profile is used to activate the plugin. By setting <extensions>true</extensions>, the plugin hooks into the Maven lifecycle to intercept the build process and calculate which modules actually need to run based on Git history.
3. IDE Compatibility: A clever profile named disable-gib-in-intellij is automatically activated when the idea.version property is present. This disables GIB (gib.disable=true) when working inside IntelliJ IDEA, preventing it from interfering with the IDE’s internal incremental compilation and ensuring a smooth developer experience.

Integration with GitHub Actions

The oss-feature-build.yml workflow implements a sophisticated two-step strategy to leverage incremental builds in CI:

• Step 1: The Primer (Fast Build)
  The workflow first runs a “Fast Build” (-Pfast-build -Dgib.disable install). This step explicitly disables GIB and skips heavy tasks like tests and Checkstyle. Its purpose is to “prime” the local Maven repository by installing all modules, ensuring that artifacts for unchanged modules are available as dependencies for the next step.
• Step 2: Targeted Validation (Incremental Build)
  The core CI build runs clean install but uses GIB to limit execution. It dynamically detects the default branch (e.g., master or main) and passes it via -Dgib.referenceBranch. GIB then analyzes the Git diff between the feature branch and the reference branch, selecting only the changed modules—and any downstream modules that depend on them—for testing and building.

Why Incremental Builds for Monorepos?

1. Reduced Feedback Loops: Developers receive PR feedback in minutes rather than hours, as unrelated modules are skipped entirely.
2. Resource Efficiency: By avoiding redundant work, the project significantly reduces the consumption of GitHub Actions runner minutes, lowering CI costs.
3. Automated Dependency Tracking: GIB ensures safety by automatically identifying and building downstream dependents of changed modules, catching potential integration breaks that a simple “changed-files-only” approach would miss.
4. Scalability: As the monorepo grows from 10 modules to 100, the build time for a single-module change remains constant rather than scaling linearly.

Working example

Lime Mojito OSS Development Standard Build (GitHub)

Maven dependency conflicts are one of the most frustrating issues developers encounter when building Java applications. When multiple versions of the same library exist in your classpath, it can lead to runtime errors, unexpected behavior, and difficult-to-debug issues. This article provides a comprehensive guide to identifying, understanding, and resolving JAR version conflicts in Maven projects.

Understanding Dependency Conflicts

What Are Dependency Conflicts?

Dependency conflicts occur when your project’s dependency tree contains multiple versions of the same artifact (same groupId and artifactId but different versions). Maven’s dependency resolution mechanism will choose one version based on its rules, but this choice might not be compatible with all parts of your application.

Common Symptoms

• ClassNotFoundException or NoClassDefFoundError at runtime
• NoSuchMethodError or AbstractMethodError
• IncompatibleClassChangeError
• Unexpected behavior in libraries that worked in isolation
• Different behavior between development and production environments

Identifying Conflicts

1. Using Maven Dependency Plugin

The most effective way to identify conflicts is using Maven’s built-in dependency plugin:

mvn dependency:tree

This command shows your complete dependency tree. Look for multiple versions of the same artifact:

[INFO] +- com.fasterxml.jackson.core:jackson-core:jar:2.13.0:compile
[INFO] +- com.fasterxml.jackson.core:jackson-databind:jar:2.13.0:compile
[INFO] |  \- com.fasterxml.jackson.core:jackson-core:jar:2.12.0:compile (omitted for conflict with 2.13.0)

2. Analyzing Conflicts with Verbose Output

For more detailed conflict analysis:

mvn dependency:tree -Dverbose

This shows which dependencies are omitted due to conflicts and why Maven chose specific versions.

3. Using the Dependency Analyze Goal

mvn dependency:analyze

This command identifies:

• Used undeclared dependencies
• Unused declared dependencies
• Potential conflicts

4. IDE-Based Analysis

Most modern IDEs provide visual dependency analysis:

• IntelliJ IDEA: Right-click on pom.xml → Analyze Dependencies
• Eclipse: Project Properties → Java Build Path → Libraries → Maven Dependencies

Understanding Maven’s Resolution Strategy

Maven uses these rules to resolve conflicts:

1. Nearest Definition: Dependencies closer to the root in the dependency tree win
2. First Declaration: If dependencies are at the same depth, the first one declared wins
3. Version Range: Explicit version ranges override transitive dependencies

Resolution Strategies

1. Explicit Dependency Declaration

The most straightforward approach is to explicitly declare the version you want:

<dependencies>    
  <dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-core</artifactId>
    <version>2.13.0</version>
  </dependency>
</dependencies>

2. Dependency Management Section

Use the <dependencyManagement> section to centrally manage versions:

<dependencyManagement>    
  <dependencies>        
    <dependency>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-core</artifactId> 
      <version>2.13.0</version>   
    </dependency>
  </dependencies>
</dependencyManagement>

3. Excluding Transitive Dependencies

Exclude problematic transitive dependencies:

<dependency>    
  <groupId>org.springframework</groupId>  
  <artifactId>spring-web</artifactId>   
  <version>5.3.0</version>  
  <exclusions>
     <exclusion>     
        <groupId>com.fasterxml.jackson.core</groupId>       
        <artifactId>jackson-core</artifactId>  
        </exclusion>  
     </exclusions>
</dependency>

4. Using Maven Enforcer Plugin

Prevent conflicts by failing the build when they occur:

<plugin>    
  <groupId>org.apache.maven.plugins</groupId> 
  <artifactId>maven-enforcer-plugin</artifactId>
  <version>3.0.0</version> 
  <executions>       
    <execution>
       <id>enforce-no-duplicate-dependencies</id>        
       <goals>            
         <goal>enforce</goal>       
       </goals>  
       <configuration>       
          <rules>                
            <dependencyConvergence/>        
            <requireNoRepositories/>           
          </rules>  
       </configuration>   
     </execution>
   </executions>
</plugin>

Advanced Debugging Techniques

1. Creating a Dependency Report

Generate detailed dependency reports:

mvn project-info-reports:dependencies

This creates an HTML report showing all dependencies and their relationships.

2. Using Maven’s Debug Output

Run Maven with debug output to see detailed resolution information:

mvn -X dependency:tree

3. Checking Effective POM

View the effective POM to see resolved dependencies:

mvn help:effective-pom

Best Practices

1. Use Bill of Materials (BOM)

Import BOMs for consistent dependency versions:

<dependencyManagement>  
  <dependencies>       
    <dependency>       
      <groupId>org.springframework.boot</groupId>    
      <artifactId>spring-boot-dependencies</artifactId>      
      <version>2.7.0</version>     
      <type>pom</type>      
      <scope>import</scope>      
    </dependency>    
  </dependencies>
</dependencyManagement>

2. Regular Dependency Updates

Keep dependencies up to date and use tools like:

• mvn versions:display-dependency-updates
• mvn versions:use-latest-releases

3. Minimize Direct Dependencies

Reduce the number of direct dependencies to minimize conflict opportunities.

4. Use Dependency Scopes Appropriately

• compile: Default scope
• provided: Available at compile time but not packaged
• runtime: Not needed for compilation but required at runtime
• test: Only available during testing

Preventing Future Conflicts

1. Establish Dependency Governance

• Create a team-wide dependency management strategy
• Use parent POMs for version consistency
• Regular dependency audits

2. Automated Conflict Detection

Integrate conflict detection into your CI/CD pipeline:

<plugin>    <groupId>org.apache.maven.plugins</groupId>    <artifactId>maven-dependency-plugin</artifactId>    <executions>        <execution>            <goals>                <goal>analyze-only</goal>            </goals>            <configuration>                <failOnWarning>true</failOnWarning>            </configuration>        </execution>    </executions></plugin>

3. Version Range Strategy

Be cautious with version ranges. Prefer specific versions for stability:

<!-- Avoid --><version>[1.0,2.0)</version>
<!-- Prefer --><version>1.5.2</version>

Common Conflict Scenarios

Spring Framework Conflicts

Spring projects often have complex dependency trees. Use Spring Boot’s dependency management or Spring Framework BOM.

Logging Framework Conflicts

Multiple logging frameworks (Log4j, Logback, Commons Logging) often conflict. Use SLF4J as a facade and bridge other frameworks.

Jackson Library Conflicts

Jackson modules must use compatible versions. Manage them centrally in dependencyManagement.

Conclusion

Debugging Maven dependency conflicts requires a systematic approach:

1. Identify conflicts using Maven tools
2. Understand Maven’s resolution strategy
3. Apply appropriate resolution techniques
4. Prevent future conflicts with good practices

The key is to be proactive rather than reactive. Establish good dependency management practices early in your project lifecycle, and use automated tools to catch conflicts before they reach production.

Remember that dependency conflicts are often symptoms of deeper architectural issues. Sometimes the best solution is to refactor your application to reduce complex dependency chains rather than working around conflicts with exclusions and forced versions.

By following these practices and using the tools outlined in this article, you’ll be well-equipped to handle even the most complex dependency conflict scenarios in your Maven projects.