Java Build with Maven

Scope

In scope:

• •Create/standardize parent POM and multi-module structure.
• •Pin plugin versions via pluginManagement.
• •Centralize dependency versions via dependencyManagement (BOMs allowed).
• •Add Maven Enforcer rules for Java/Maven versions and dependency convergence.
• •Define profiles for environments (dev/test/prod) if needed.
• •Document reproducible build steps.

Out of scope:

• •CI pipeline authoring (only provide commands).
• •Framework-specific starters unless requested.
• •Rewriting code unrelated to build.

When to use

• •Build fails or behaves inconsistently across machines.
• •Adding modules; migrating to multi-module reactor.
• •Needing strict plugin/dependency version control.
• •Security reviews requiring pinned build toolchain behavior.

Inputs

• •Current pom.xml(s), module list, publishing requirements.
• •Target Java version(s) and runtime constraints.
• •Existing profiles and settings (private repos, proxies).

Procedure

1. •

   Wrapper + baseline

   • •Ensure Maven Wrapper exists (./mvnw) and is the canonical entrypoint.
   • •Ensure .mvn/ config exists for consistent JVM flags if needed.
2. •

   Reactor structure (multi-module)

   • •Create a root pom.xml packaging pom.
   • •Define <modules> list.
   • •Move shared configuration to parent.
3. •

   Dependency governance

   • •Use <dependencyManagement> to pin versions.
   • •Use BOMs where appropriate.
   • •Ensure no module declares arbitrary versions when managed.
4. •

   Plugin governance

   • •Pin plugin versions in <pluginManagement>.
   • •Ensure surefire/failsafe versions are pinned.
   • •Keep compiler plugin aligned with target Java version.
5. •

   Enforcer hardening

   • •Add Enforcer with rules:
     • •RequireMavenVersion
     • •RequireJavaVersion
     • •DependencyConvergence (or equivalent)
   • •Fail fast with actionable messages.
6. •

   Profiles (optional)

   • •Use profiles for environment-specific settings only.
   • •Avoid profiles that change core dependency graphs unexpectedly.
7. •

   Documentation

   • •Update README with canonical commands:
     • •./mvnw -q test
     • •./mvnw -q -DskipTests package
     • •./mvnw -q -P<profile> verify (if profiles exist)

Outputs

• •Parent POM + module POMs standardized.
• •Enforcer rules added.
• •Reproducible build steps documented.

DoD

• • Clean checkout builds with ./mvnw -q test.
• • Modules are listed and build in reactor order.
• • Dependencies and plugins are pinned/governed.
• • Enforcer catches wrong Java/Maven versions early.

Guardrails

• •Do not introduce too many profiles; keep them minimal.
• •Do not allow unmanaged dependency versions without explicit reason.
• •Do not weaken enforcer rules to “make it pass” without root-cause analysis.

Failure modes & fixes

• •"Different results across machines" → missing wrapper/pinned plugins → add wrapper + pluginManagement.
• •"Dependency diamond conflicts" → no convergence checks → add enforcer + dependencyManagement.
• •"CI uses wrong Java" → missing RequireJavaVersion → enforce and document.

References

• •See templates/ for parent/module POM examples and .mvn/ config.
• •See references/ for profile and plugin governance playbooks.