Maven 4 Preview, Build Consumer POM, Compatibility, Migration Planning, and Maven 3 Production Baselines: Concepts, Architecture, and Mental Model

1. The practical problem: a Maven upgrade changes the interpreter of your build

Under Maven 3, your repository contains a declared model—usually a pom.xml using model 4.0.0—plus wrapper files, plugins, dependencies, settings boundaries, and CI assumptions. Maven core reads that model and orchestrates plugin code. Changing Maven core changes the interpreter and therefore can change validation rules, lifecycle semantics, plugin APIs, model transformation, warnings, or publication metadata even when the Java source code is unchanged.

The migration question is therefore not “does mvn verify exit zero under Maven 4?” It is: does the intended model still mean the same thing, do the required plugins/extensions still execute correctly, do tests and artifacts remain trustworthy, and can we roll back without damaging published state?

2. Release status is part of the build specification

3. Separate the Maven runtime JDK from the project target JDK

Maven 4 itself needs Java 17 or newer. That is the Java runtime that starts Maven core and loads plugins. Your project can still compile for a different supported target through the Maven Compiler Plugin or toolchains. In the lab we intentionally run both Maven 3.9.16 and Maven 4.0.0-rc-6 on JDK 21 and compile with release=17. Holding the launcher JDK constant prevents a Maven-vs-JDK confounding variable.

<properties>
  <maven.compiler.release>17</maven.compiler.release>
</properties>

If the Maven 4 lane fails because CI still uses Java 11, that is an environment-migration finding—not evidence that the application itself must suddenly target Java 17.

4. Build POM, effective model, and consumer POM are different artifacts

The build POM is the repository-owned model Maven uses to build the project. The effective model is Maven's merged/interpolated view after parent inheritance, defaults, profiles, and plugin management. A consumer POM is the downstream-facing metadata Maven 4 can derive for installed/deployed artifacts so consumers receive dependency/project information without unnecessary build-only detail.

flowchart TD
  A[Build POM in source] --> B[Maven 4 model builder]
  B --> C[Effective build model]
  C --> D[Plugin lifecycle execution]
  C --> E[Consumer POM transformation]
  D --> F[JAR / reports]
  E --> G[Installed or deployed consumer metadata]
  F --> H[Artifact repository]
  G --> H

The first arrow is source interpretation. The second creates execution state. Lifecycle plugins produce artifacts and reports. Separately, Maven 4 can transform the build model into consumer-oriented metadata for installation/deployment. A successful transformation is not permission to publish to production; publication remains its own trust transition.

5. What the consumer-POM idea is solving

Build metadata such as compiler-plugin configuration helps produce an artifact but is usually irrelevant to a downstream project that merely consumes it. Maven 4 can publish a stripped/translated consumer POM, commonly represented as model 4.0.0 so Maven 3 and other consumers can keep resolving the artifact even if the source build POM uses Maven 4-only model features.

Current Maven documentation describes consumer POMs as removing build-only information, resolving inherited content, and preserving consumer-relevant dependency metadata. Do not assume the installed POM must textually match the source pom.xml. Instead verify the downstream contract: coordinates, dependency scopes/versions, repositories where appropriate, and the consumer's ability to resolve the artifact.

6. Model 4.1.0 is a feature boundary, not step one

Maven 4 can build ordinary model 4.0.0 projects. Apache's migration guide recommends first making the latest Maven 3 build clean, then testing that same Maven 3-compatible model under Maven 4, and only after compatibility is established introducing Maven 4-only features. Model 4.1.0 enables features such as a root attribute, <subprojects>, dedicated bom packaging, and richer inference, but a 4.1.0 build POM cannot be built by Maven 3.

7. Compatibility is wider than the POM schema

A Maven 4 readiness review must inventory: core extensions under .mvn/extensions.xml; plugins and their versions; scripts that parse exact log text; CI images and JDKs; Enforcer rules that constrain Maven versions; lifecycle bindings to phases whose semantics changed; custom tooling that uses Maven internal APIs; repository/publishing behavior; and any assumption that the source POM is byte-for-byte what downstream consumers receive.

Maven 4 aims to run Maven 3.9-compatible plugins that do not depend on old Maven 2/internal APIs, but that goal is not a guarantee for every plugin or extension. Compatibility belongs to each actual build graph.

8. Examples of Maven 4 behavior that deserve explicit review

Several Maven 4 changes are intentionally visible migration topics. Examples include stricter handling of malformed/duplicate declarations, new before:/after: lifecycle concepts replacing old pre/post patterns in relevant cases, changed install/deploy-at-end defaults, new root/subproject model features, and consumer-POM transformation. The point is not to memorize every Maven 4 feature now; the point is to recognize every changed semantic as a migration hypothesis requiring evidence.

9. mvnup is a migration assistant, not an approval authority

The Maven Upgrade Tool ships with Maven 4 from rc-4 onward. mvnup check analyzes and reports changes; mvnup apply edits POM files. Its default target model is 4.0.0, while --model-version 4.1.0 opts into Maven 4-only model syntax.

# From a verified Maven 4 distribution, read-only first:
mvnup check
mvnup check --model-version 4.1.0 --all

# Apply only in a disposable branch/copy after review:
mvnup apply --model-version 4.1.0 --all

The safe order is check → save output → review diff → build/test → compare artifacts/metadata → decide. “mvnup had no objections” is not equivalent to plugin, extension, CI, or artifact compatibility.

10. DevOps connection: major tool upgrades are platform migrations

A team standardizing Maven 4 changes developer bootstrapping, CI runner images, wrapper distributions, plugin compatibility, diagnostics, and possibly published metadata. That is platform work. A production migration needs an owner, test matrix, rollback path, artifact comparison, release-status gate, and a policy for when Maven 4-only POM features become allowed.

Knowledge check

11. Bridge to the guided workflow

Lesson 2 creates two independently pinned lanes from the same source. You will verify the Maven 4 distribution before trusting it, compare builds and checksums, run mvnup check, then make a separate Maven 4-only model 4.1.0 copy to inspect consumer metadata without damaging the Maven 3 baseline.

Official references and version notes

Version-sensitive statements in this lesson were checked against current Apache Maven primary documentation on 2026-08-24.

• Maven releases history — Current GA and Maven 4 release-candidate status, release dates, and Java requirements.
• What is new in Maven 4 — Java 17 runtime requirement, consumer POM, model 4.1.0 features, BOM packaging, and Maven 4 behavior.
• Starting with Maven 4 — Official prepare → test → migrate strategy, compatibility changes, model 4.1.0 guidance, and rollback-friendly staging.
• Maven Upgrade Tool (mvnup) — Built-in Maven 4 migration tool, check/apply workflow, and 4.0.0 versus 4.1.0 target behavior.
• Maven 4.0.0-rc-6 release notes — Current RC status, migration notes, fixed RC-5 issues, and remaining known issues.
• Apache Maven Wrapper 3.3.4 — Stable wrapper release and integrity-capable wrapper behavior.