You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by hb...@apache.org on 2026/08/01 11:21:11 UTC
(maven-site) branch m4doc updated: additional Maven 4 doc improvements
This is an automated email from the ASF dual-hosted git repository.
hboutemy pushed a commit to branch m4doc
in repository https://gitbox.apache.org/repos/asf/maven-site.git
The following commit(s) were added to refs/heads/m4doc by this push:
new d2597b1a additional Maven 4 doc improvements
d2597b1a is described below
commit d2597b1ac97408c5aaf576c48de6b8f01800564f
Author: Hervé Boutemy <hb...@apache.org>
AuthorDate: Sat Aug 1 12:20:26 2026 +0100
additional Maven 4 doc improvements
---
content/markdown/docs/history.md.vm | 5 ++
.../guides/mini/guide-migration-to-mvn4.md | 59 ++++++++++++----------
content/markdown/whatsnewinmaven4.md | 8 +--
3 files changed, 42 insertions(+), 30 deletions(-)
diff --git a/content/markdown/docs/history.md.vm b/content/markdown/docs/history.md.vm
index e7804931..9287bee4 100644
--- a/content/markdown/docs/history.md.vm
+++ b/content/markdown/docs/history.md.vm
@@ -66,6 +66,11 @@ Currently, plugins provide Maven API compatibility down to **3.9.0**. See [Maven
$esc.h$esc.h Maven 4.0+ (not yet GA)
+
+Maven 4.x is a major release that includes significant improvements and changes: see [What's new in Maven 4?](/whatsnewinmaven4.html) article for more details.
+
+See also [Starting with Maven 4](/guides/mini/guide-migration-to-mvn4.html) guide to get safe upgrade instructions.
+
<table>
<tr><th>Release Date</th>
<th>Version</th>
diff --git a/content/markdown/guides/mini/guide-migration-to-mvn4.md b/content/markdown/guides/mini/guide-migration-to-mvn4.md
index 2a40dcce..03c66f98 100644
--- a/content/markdown/guides/mini/guide-migration-to-mvn4.md
+++ b/content/markdown/guides/mini/guide-migration-to-mvn4.md
@@ -20,7 +20,7 @@ under the License.
-->
Maven 4 introduces several updates and improvements (see ["What's new in Maven 4?"](/whatsnewinmaven4.html)).
-Some of them are backwards compatible with Maven 3 or optional, but some require changes of your build environment or Maven project.
+Some of them are backwards compatible with Maven 3, but some require changes of your build environment or Maven project.
This page offers help for users who want to build their projects with Maven 4 (and check with RCs that everything is fine).
In short, the general suggestion for the migration is to do it in three steps:
@@ -42,7 +42,7 @@ Many OSS projects have already published releases to [Maven Central with Maven 4
* This guide does not contain information about how to update plugins to use the new Maven 4 plugin API.
We plan to create a separate guide for this when we'll work on Maven 4.1: for now, we focus on using Maven 4.0.x (RC) with classical Maven 3 plugins.
-## Table of content
+**Table of content**
<!--MACRO{toc|fromDepth=2|toDepth=4}-->
@@ -160,6 +160,13 @@ Update your plugin executions that bind to a `pre-integration-test` or `post-int
## Step 3 -- migrate: Drop Maven 3, use Optional Maven 4 features
+In this step, we'll update your project's `pom.xml` to benefit from new Maven 4 features that are not available in Maven 3:
+by applying required changes, you won't be able to build your project with Maven 3 any more.
+
+Notice that [Maven 4 Consumer POM](/whatsnewinmaven4.html#Consumer_POM) will automatically be triggered, which makes sure the
+output of your project can still be used by any tool, be it Maven 3 or other build tools: only **building** your project from `pom.xml`
+in your source control (aka. *Build POM*) requires Maven 4.
+
### Changed default values
#### Install/deploy at end of build (breaking change)
@@ -192,7 +199,7 @@ When the root directory is not defined, the following warning is displayed:
> [WARNING] Unable to find the root directory. Create a .mvn directory in the root directory or add the root="true" attribute on the root project's model to identify it.
-As written in the warning there are two ways to define the root directory:
+As written in the warning, there are two ways to define the project's root directory:
1. Create a `.mvn` directory in the root directory.
From Maven's perspective, the directory can be empty, but some version control systems do not check in an empty directory.
@@ -204,35 +211,35 @@ As written in the warning there are two ways to define the root directory:
#### Use `<subprojects>` instead of `<modules>`
-In Maven 4 subprojects are no longer called modules.
+In Maven 4 subprojects are no longer called modules, to avoid confusion between *Maven modules* and *Java Modules* introduced in Java 9.
While the `<modules>` element is still supported, it was marked as deprecated in model version 4.1.0 and will get removed in a future version.
So you should replace it with the new `<subprojects>` element instead.
```xml
<!-- Requires model version 4.0.0 (Maven 3, deprecated in model version 4.1.0) -->
<modules>
- <module>ModuleA</module>
- <module>ModuleB</module>
+ <module>moduleA</module>
+ <module>moduleB</module>
</modules>
<!-- Requires model version 4.1.0 (Maven 4) -->
<subprojects>
- <subproject>ModuleA</subproject>
- <subproject>ModuleB</subproject>
+ <subproject>moduleA</subproject>
+ <subproject>moduleB</subproject>
</subprojects>
```
#### Automatic versioning in multi subprojects setups
Maven 4 contains a lot of improvements for projects which contain subprojects.
-Those include automatic version detection of the parent and project own dependencies.
+Those include automatic version detection of the parent and project own dependencies, and automatic detection of parent groupId and artifactId.
-Using Maven 3 with model version 4.0.0 you need to declare those.
-While the parent's version always must be hardcoded, you can use the `${project.version` property to declare another subproject as a dependency.
-Using Maven 4 and model version 4.1.0 those definitions are optional.
+Using Maven 3 with model version 4.0.0, you need to declare those.
+While the parent's version always must be hardcoded, you can use the `${project.version}` property to declare another subproject as a dependency.
+Using Maven 4 and model version 4.1.0, those definitions are optional: they are automatically inferred from content on disk.
-The following example of a pom.xml shows the associated part for a subproject called "SubprojectB".
-This subproject declares its parent and the dependency to "SubprojectA", which is also a subproject in the same multi subproject setup.
+The following example of a `pom.xml` shows the associated part for a subproject called "subprojectB".
+This subproject declares its parent and the dependency to "subprojectA", which is also a subproject in the same multi subproject setup.
In Maven 3 with model version 4.0.0 such a declaration looks like the following.
@@ -242,19 +249,20 @@ In Maven 3 with model version 4.0.0 such a declaration looks like the following.
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
- <artifactId>SubprojectB</artifactId>
+ <artifactId>subprojectB</artifactId>
<parent>
+ <!-- The parent groupId and artifactId must be "hardcoded" -->
<groupId>demo.maven</groupId>
- <artifactId>TheParentProjecct</artifactId>
- <!-- The parents version must be "hardcoded" -->
+ <artifactId>theParentProjecct</artifactId>
+ <!-- The parents' version must be "hardcoded" -->
<version>0.0.1-SNAPSHOT</version>
</parent>
<dependencies>
<dependency>
<groupId>demo.maven</groupId>
- <artifactId>SubprojectA</artifactId>
+ <artifactId>subprojectA</artifactId>
<!-- The subproject dependency version declaration can make use of the project.version property-->
<version>${project.version}</version>
</dependency>
@@ -264,7 +272,7 @@ In Maven 3 with model version 4.0.0 such a declaration looks like the following.
</project>
```
-In Maven 4 and model version 4.1.0 the version declaration is not needed anymore.
+In Maven 4 and model version 4.1.0, the version declarations and parent coordinates are not needed anymore.
```xml
<project xmlns="http://maven.apache.org/POM/4.1.0"
@@ -272,17 +280,14 @@ In Maven 4 and model version 4.1.0 the version declaration is not needed anymore
xsi:schemaLocation="http://maven.apache.org/POM/4.1.0 http://maven.apache.org/xsd/maven-4.1.0.xsd">
<modelVersion>4.1.0</modelVersion>
- <artifactId>SubprojectB</artifactId>
+ <artifactId>subprojectB</artifactId>
- <parent>
- <groupId>demo.maven</groupId>
- <artifactId>TheParentProjecct</artifactId>
- </parent>
+ <parent/>
<dependencies>
<dependency>
<groupId>demo.maven</groupId>
- <artifactId>SubprojectA</artifactId>
+ <artifactId>subprojectA</artifactId>
</dependency>
</dependencies>
@@ -312,7 +317,7 @@ The following code snippet shows an example for a BOM POM using the new `<packag
<modelVersion>4.1.0</modelVersion>
<groupId>demo.maven</groupId>
- <artifactId>Maven4-example-bom</artifactId>
+ <artifactId>maven4-example-bom</artifactId>
<version>1.0.0</version>
<packaging>bom</packaging>
@@ -354,7 +359,7 @@ Maven 3 has two explicitly named XML elements (`<sourceDirectory>` and `<testSou
```
Maven 4 introduces the new `<sources>` element for this.
-This makes source directory declarations more flexible for future improvements.
+This makes source directory declarations more flexible for future improvements like Java Modules.
When migrate to Maven 4, you should use the new element.
```xml
diff --git a/content/markdown/whatsnewinmaven4.md b/content/markdown/whatsnewinmaven4.md
index 6e6452cf..b34ebb84 100644
--- a/content/markdown/whatsnewinmaven4.md
+++ b/content/markdown/whatsnewinmaven4.md
@@ -569,8 +569,10 @@ Together, these new phases provide a powerful and intuitive structure for defini
As mentioned above, Maven 4 contains significant code and API updates, resulting in breaking changes for (very) old
Maven 2 plugins that have not been [updated to use the recommended Maven 3 APIs](https://cwiki.apache.org/confluence/display/MAVEN/Plugin+migration+to+Maven3+dependencies) and [other cleanup](https://cwiki.apache.org/confluence/display/MAVEN/Maven+Ecosystem+Cleanup).
-You can enable them by passing the following argument to your build: `-Dmaven.plugin.validation=verbose`.
-You should also only rely on the official Maven BOMs when developing plugins.
+You can enable verbose plugin validation by passing the following argument to your build: `-Dmaven.plugin.validation=verbose`
+(see detailed [plugin validation guide](/guides/plugins/validation/index.html)).
+
+You should also only rely on the [official Maven BOMs](https://central.sonatype.com/artifact/org.apache.maven/maven-bom) when developing plugins.
If a plugin still relies on long-deprecated and now removed Plexus dependency injection, it will no longer work.
It needs to be updated to use JSR-330 - see [Maven & JSR-330][26] for further information.
@@ -581,7 +583,7 @@ Pay close attention to upcoming warnings and update the plugin accordingly.
Maven 4 is expected to be able to run any Maven 3 plugin that has been updated to Maven 3 best practices (instead of using Maven 3's ability to [run Maven 2 plugins](https://cwiki.apache.org/confluence/display/MAVEN/Compatibility+with+Maven+2.x) and other old APIs...).
Major changes regarding plugins include a proper immutable plugin model together with a revised plugin API for Maven 4.
-But this new Maven 4 API is still in experimental phase in Maven 4.0.0: do not yet try to use it unless you precisely know what you are doing (like [Maven Compiler Plugin 4.x](/plugins/maven-compiler-plugin-4.x/)).
+But this new Maven 4 API is still in experimental phase in Maven 4.0.0: do not yet try to use it unless you precisely know what you are doing (like [Maven Compiler Plugin 4.x](/plugins/maven-compiler-plugin-4.x/) for Java Modules).
### Improved encryption