You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@maven.apache.org by "Bukama (via GitHub)" <gi...@apache.org> on 2024/12/17 16:35:40 UTC
[PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Bukama opened a new pull request, #598:
URL: https://github.com/apache/maven-site/pull/598
This PR adds an article about the major changes in Maven 4.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "cstamas (via GitHub)" <gi...@apache.org>.
cstamas commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894104074
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's new in Maven 4?
+
+Maven is over 20 years old and is one of the most used build-tool in the Java world.
+Since all the years one important rule was the highest backward-compatibility as possible, especially with
+its [POM-schema with Model version 4.0.0][2], used for the build itself, but also by consumers.
+This made Maven more than a tool, but a whole ecosystem with a lot of things depended on the POM, esp. the Maven Central
+repository, other build tools and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare to changes which are impossible nowadays, like a complete new build schema.
+
+Another pain point of Maven 3 is a code base with a lot of deprecated, convoluted, non performant and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebases contains old Java code that can be optimized nowadays, but also old
+dependencies and bad API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM-Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction the Model version 4.0.0 is used not only for the build, but also by consumers of the
+artifact.
+But several contents of the POM are only necessary for the build while others like the dependencies are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As names suggest the "Build-POM" will contain all information needed for to build the artifact, e.g. used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep those which are really needed to use the artifact, e.g. dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4 a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others got marked as deprecated.
+To not break the ecosystem this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as like every software update - it's suggested to update them to 4.1.0, e.g. to avoid problems when deprecated
+things get removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 till today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files the wording "Maven project" is used.
+However, project containing multiple parts, e.g. an API and a client, each of those parts was called "module" and listed
+in the `<modules>` section of the POM, leading to the terms of "multi-module project".
+This wording introduced some inconsistency, especially as projects with any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9 the term "module" raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>`analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency managing BOMs.
+While the new type is only available with model Version 4.1.0 the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2004][5].
+
+**Note**: With Maven 4 it's also possible to exclude dependencies which are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven4 importing BOMs with classifier is now possible.
+Therefore, Maven team suggests that projects BOMs be generated as classified artifacts (see Maven build "skinny" vs "
Review Comment:
Our stance (@gnodet could chime in when online) is following: BOMs should be _generated_ and not used within reactor (see issues), because users are "tempted" to create BOMs within reactor (is fine, as long BOM is "published only"), and then reuse BOM in same way as any external BOM would be reused: by importing within reactor. But, importing within reactor causes "build peculiarities" usually unexpected to users. Hence, we think that _generating BOMs_ simply prevents the two issues, as reactor dependendencies should be managed using inheritance, as it was always the case with Maven. Appearance of BOMs simply caused this "boost of creativity", to reuse them within reactor, but also publish them to downstream users, and it is wrong. Hence, Maven 4 shows an "example", and generates it's own BOMs. Related https://issues.apache.org/jira/browse/MNG-8012 and https://issues.apache.org/jira/browse/MNG-8009
In short: only external BOMs should be imported to reactor.
As per "what is a BOM", there is a split among us as can be seen in this old PR: https://github.com/apache/maven/pull/689
For some, "[BOM represents only the set of modules of a multimodule](https://github.com/apache/maven/pull/689#issuecomment-1061640064)" (only the reactor, so to say) while for others (@gnodet and me included) "BOM is bill of materials", so full stack: if I do an extension for Maven version X, I want same version of Resolver, Logging, Sisu etc that Maven X use as well... Similarly, look at all our plugins: after version property defining Maven version that plugins builds against, property is usually followed by a section with bunch of "keep in lockstep with Maven" version properties for logging, resolver, etc. All this is just noise and should not be needed. Hence, the "skinny" (first definition) vs "fat" (second definition). In fact, Maven4 generates both now, so pleases both parties.
Of course, Maven 4 build generated BOMs can be used only in Maven 4 builds, as only Maven 4 allows importing BOMs with classifiers... So for Maven3, this is still an issue.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on PR #598:
URL: https://github.com/apache/maven-site/pull/598#issuecomment-2558133391
Hope everything is fine now :)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1898710847
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
Review Comment:
> That's not obvious to me
Explanation added (will be visible after next push)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "elharo (via GitHub)" <gi...@apache.org>.
elharo commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1898685481
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicate code
+which costs the volunteers who maintain Maven a lot of time.
+This means that the Maven codebase contains not only old Java code that can be optimized nowadays but also old
Review Comment:
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "cstamas (via GitHub)" <gi...@apache.org>.
cstamas commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1931962415
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,477 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is the most widely used build tool in the Java world.
+Throughout the years, Maven has maintained backward compatibility, especially of its [POM file][2] with Model version
+4.0.0.
+
+The POM file fulfills two needs.
+First, the POM holds all the information and configuration, which are needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, for example dependencies, which are needed by projects which depend on the
+artifact.
+These dependent projects are called the "consumers".
+
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+Thus, any change in the POM's schema forces each participant of the ecosystem to either adopt the change or drop
+support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+In order for Maven to evolve, it's necessary to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## Required Java version
+
+Maven 4 requires Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 is only needed to **run Maven**!
+You can still compile against older Java versions using the same [compiler plugin configuration][6] as before.
+If you need to compile against or use another JDK, see the [Guide to Using Toolchains][7] (or the
+article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten Mulders).
+
+## POM Changes
+
+### Consumer POM
+
+Maven 4 generates a stripped down consumer POM that removes build information not needed by consumers, and deploys this
+to the remote repository.
+It does not deploy the `pom.xml` used to build the project.
+
+### Model version 4.1.0
+
+Maven 4 updates the POM version to 4.1.0 which defines the namespace `http://maven.apache.org/POM/4.1.0`.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the build POM, while the consumer POM will still use
+version 4.0.0.
+Maven generates the consumer POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 if you don't need to use the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project built with Maven.
+The [top level directory][32] of a Maven project contains at least the source folder `src` and the project's POM file
+`pom.xml`.
+A Maven project may have other Maven projects within subdirectories, each with its own `pom.xml` file.
+Each project within a subdirectory is called a "subproject".
+
+Example: Project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects unless they are linked from the root POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+Projects which have at least one subproject are called "multi-module projects", while those which do not have any
+subprojects are called "single module projects".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated `bom` packaging type to provide a [Bill of Materials BOM][4].
+This now differentiates between parent POMs and dependency-managing BOMs.
+The new type is only available as a build POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible consumer POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build.
+In other words: you should only import external BOMs.
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing build POM and consumer POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "consumer POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, for example plugin configuration!
+* Some of the build-related content which is (as of now) still available in the consumer POM might be available only in
+ the build POM in the future.
+
+| Content | Build POM | Consumer POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a consumer POM based on version 4.1.0, for example
+when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, for example a `maven.config` or
+`jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the build POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, for example when you want to define the path to a `checkstyle-suppressions.xml`
+file for the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+current working directory.
+The `rootDirectory` can only contain a value when either a `.mvn` directory is defined or the `root` attribute is set to
+true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4 those properties were removed or marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 consumer POM is set in stone, the build POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, like `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration.
+
+Example
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, for example `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects can cause confusion in Maven 3.
+When the build of subproject B, which requires subproject A, is failing for whatever reason, Maven 3 is telling
+the user to fix the error and then resume the build with `--resume-from :<nameOfTheFailingSubproject>`.
+But doing this instantly fails the build again, because the required subproject A couldn't be found (as it was not
+rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (for example Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where successfully
+built subprojects were deployed to the (local or remote) repository, but failed subprojects were not.
+This was finally changed in Maven 4 to what most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+in Maven 3, for example using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, always define fixed versions of all the plugins you use.
+By doing this, you are in control of your build.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM.
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which breaks the build when the severity of at least one log
+message matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, for example, `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break.
+Instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+In Maven 3 the lifecycle is an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more fine-grained execution of dependent phases.
+For example, the `compile` phase must execute after `compile-only` project dependencies have reached the `ready` phase.
+Maven 4 also allows to skip phases (in comparison to the old graph).
+For example, it's possible to `deploy` an artifact without `install`ing it to the user repository.
+
+For compatibility, the execution behavior is not really changed by default compared to Maven 3.
+In order to actually leverage the new tree-based lifecycle, the user has to enable the concurrent builder using
+`-b concurrent`.
+Running with the concurrent builder will allow finer grained dependency instead of the usual Maven 3 per-project
+dependency.
+With the usual builders and run `mvn verify`, a project will run up to the verify phase, before a dependent project can
+start being built, whereas the concurrent builder will allow a dependant project to be built as soon as the dependencies
+are at the `ready` phase.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before:` and an `after:` phase, allowing plugins to bind themselves to those.
+For example, if you want to set up test data before running your integration tests, you could execute tasks during the
+`before:integration-test` phase.
+
+If this is not enough, perhaps because you want to do multiple things inside the same phase, you can order each
+execution inside a phase by using square brackets with an integer at the end of the phase name.
+
+Example
+
+```
+before:integration-test[100]
+before:integration-test[200]
+```
+
+**Warning**: The conceptual `pre-*` and `post-*` phases, which were only available for selected phases and had
+inconsistent naming, are deprecated.
+Don't use them!
+This becomes even more important if you are binding a plugin to the `post-*` phase of a lifecycle phase because the
+`pre-*` phase of the phase you really want to bind to does not exist, for example, binding to `process-resources` phase
+because there was no `pre-compile` phase.
+
+## Maven plugins, security, and tools
+
+### Maven plugins
+
+As mentioned above, Maven 4 contains significant code and API updates, resulting in breaking changes for (very) old
+Maven plugins that have not been updated to use the recommended APIs.
+Major changes regarding plugins include a proper immutable plugin model together with a revised plugin API.
+The updated API provides hints as preparation for Maven 4.
+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.
+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.
+
+**Advice**: If you are maintaining a Maven plugin, you should test it with Maven 3.9.x.
+Pay close attention to upcoming warnings and update the plugin accordingly.
+
+### Improved encryption
+
+Security is important, and storing unencrypted passwords is bad practice.
+Maven 3's password encryption had several serious issues and could more accurately be called "password obfuscation".
+Maven 4 instead has a completely redone encryption system, based on Maven Encryption (`mvnenc`) - a standalone CLI tool.
Review Comment:
I would not go into this distinction: plexus-sec-dispatcher is NOT an API, is not something people should use or reuse or even made aware. We already had problems with it in Maven3.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "gnodet (via GitHub)" <gi...@apache.org>.
gnodet commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1941342247
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,476 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
Review Comment:
that feature has been challenged by https://issues.apache.org/jira/browse/MNG-8537
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1915409432
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
Review Comment:
Decided to drop those lines (visible after next push)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "gnodet (via GitHub)" <gi...@apache.org>.
gnodet commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1922843182
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,468 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is the most widely used build tool in the Java world.
+Throughout the years, Maven has maintained backward compatibility, especially of its [POM file][2] with Model version
+4.0.0.
+
+The POM file fulfills two needs.
+First, the POM holds all the information and configuration, which are needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, for example dependencies, which are needed by projects which depend on the
+artifact.
+These dependent projects are called the "consumers".
+
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+Thus, any change in the POM's schema forces each participant of the ecosystem to either adopt the change or drop
+support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+In order for Maven to evolve, it's necessary to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## Required Java version
+
+Maven 4 requires Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 is only needed to **run Maven**!
+You can still compile against older Java versions using the same [compiler plugin configuration][6] as before.
+If you need to compile against or use another JDK, see the [Guide to Using Toolchains][7] (or the
+article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten Mulders).
+
+## POM Changes
+
+### Consumer POM
+
+Maven 4 generates a stripped down consumer POM that removes build information not needed by consumers, and deploys this
+to the remote repository.
+It does not deploy the `pom.xml` used to build the project.
+
+### Model version 4.1.0
+
+Maven 4 updates the POM version to 4.1.0.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the build POM, while the consumer POM will still use
+version 4.0.0.
+Maven generates the consumer POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 if you don't need to use the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project built with Maven.
+The [top level directory][32] of a Maven project contains at least the source folder `src` and the project's POM file
+`pom.xml`.
+A Maven project may have other Maven projects within subdirectories, each with its own `pom.xml` file.
+Each project within a subdirectory is called a "subproject".
+
+Example: Project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects unless they are linked from the root POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+Projects which have at least one subproject are called "multi-module projects", while those which do not have any
+subprojects are called "single module projects".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated `bom` packaging type to provide a [Bill of Materials BOM][4].
+This now differentiates between parent POMs and dependency-managing BOMs.
+The new type is only available as a build POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible consumer POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build.
+In other words: you should only import external BOMs.
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing build POM and consumer POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "consumer POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, for example plugin configuration!
+* Some of the build-related content which is (as of now) still available in the consumer POM might be available only in
+ the build POM in the future.
+
+| Content | Build POM | Consumer POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a consumer POM based on version 4.1.0, for example
+when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, for example a `maven.config` or
+`jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the build POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, for example when you want to define the path to a `checkstyle-suppressions.xml`
+file for the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+current working directory.
+The `rootDirectory` can only contain a value when either a `.mvn` directory is defined or the `root` attribute is set to
+true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4 those properties were removed or marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 consumer POM is set in stone, the build POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, like `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration.
+
+Example
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, for example `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects can cause confusion in Maven 3.
+When the build of subproject B, which requires subproject A, is failing for whatever reason, Maven 3 is telling
+the user to fix the error and then resume the build with `--resume-from :<nameOfTheFailingSubproject>`.
+But doing this instantly fails the build again, because the required subproject A couldn't be found (as it was not
+rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (for example Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where successfully
+built subprojects were deployed to the (local or remote) repository, but failed subprojects were not.
+This was finally changed in Maven 4 to what most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+in Maven 3, for example using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, always define fixed versions of all the plugins you use.
+By doing this, you are in control of your build.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM.
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which breaks the build when the severity of at least one log
+message matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, for example, `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break.
+Instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+In Maven 3 the lifecycle is an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more consistent execution of dependent phases.
+For example, the `compile` phase must execute after `compile-only` project dependencies have reached the `ready` phase.
+Maven 4 also allows to skip phases (in comparison to the old graph).
+For example, it's possible to `deploy` an artifact without `install`ing it to the user repository.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before-` and an `after-` phase, allowing plugins to bind themselves to those.
Review Comment:
The prefixes are `before:` and `after:` with `:` instead of `-`.
The same applies to the whole section of course.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1927449490
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,477 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is the most widely used build tool in the Java world.
+Throughout the years, Maven has maintained backward compatibility, especially of its [POM file][2] with Model version
+4.0.0.
+
+The POM file fulfills two needs.
+First, the POM holds all the information and configuration, which are needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, for example dependencies, which are needed by projects which depend on the
+artifact.
+These dependent projects are called the "consumers".
+
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+Thus, any change in the POM's schema forces each participant of the ecosystem to either adopt the change or drop
+support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+In order for Maven to evolve, it's necessary to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## Required Java version
+
+Maven 4 requires Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 is only needed to **run Maven**!
+You can still compile against older Java versions using the same [compiler plugin configuration][6] as before.
+If you need to compile against or use another JDK, see the [Guide to Using Toolchains][7] (or the
+article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten Mulders).
+
+## POM Changes
+
+### Consumer POM
+
+Maven 4 generates a stripped down consumer POM that removes build information not needed by consumers, and deploys this
+to the remote repository.
+It does not deploy the `pom.xml` used to build the project.
+
+### Model version 4.1.0
+
+Maven 4 updates the POM version to 4.1.0.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the build POM, while the consumer POM will still use
+version 4.0.0.
+Maven generates the consumer POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 if you don't need to use the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project built with Maven.
+The [top level directory][32] of a Maven project contains at least the source folder `src` and the project's POM file
+`pom.xml`.
+A Maven project may have other Maven projects within subdirectories, each with its own `pom.xml` file.
+Each project within a subdirectory is called a "subproject".
+
+Example: Project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects unless they are linked from the root POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+Projects which have at least one subproject are called "multi-module projects", while those which do not have any
+subprojects are called "single module projects".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated `bom` packaging type to provide a [Bill of Materials BOM][4].
+This now differentiates between parent POMs and dependency-managing BOMs.
+The new type is only available as a build POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible consumer POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build.
+In other words: you should only import external BOMs.
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing build POM and consumer POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "consumer POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, for example plugin configuration!
+* Some of the build-related content which is (as of now) still available in the consumer POM might be available only in
+ the build POM in the future.
+
+| Content | Build POM | Consumer POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a consumer POM based on version 4.1.0, for example
+when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, for example a `maven.config` or
+`jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the build POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, for example when you want to define the path to a `checkstyle-suppressions.xml`
+file for the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+current working directory.
+The `rootDirectory` can only contain a value when either a `.mvn` directory is defined or the `root` attribute is set to
+true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4 those properties were removed or marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 consumer POM is set in stone, the build POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, like `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration.
+
+Example
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, for example `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects can cause confusion in Maven 3.
+When the build of subproject B, which requires subproject A, is failing for whatever reason, Maven 3 is telling
+the user to fix the error and then resume the build with `--resume-from :<nameOfTheFailingSubproject>`.
+But doing this instantly fails the build again, because the required subproject A couldn't be found (as it was not
+rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (for example Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where successfully
+built subprojects were deployed to the (local or remote) repository, but failed subprojects were not.
+This was finally changed in Maven 4 to what most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+in Maven 3, for example using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, always define fixed versions of all the plugins you use.
+By doing this, you are in control of your build.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM.
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which breaks the build when the severity of at least one log
+message matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, for example, `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break.
+Instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+In Maven 3 the lifecycle is an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more fine-grained execution of dependent phases.
+For example, the `compile` phase must execute after `compile-only` project dependencies have reached the `ready` phase.
+Maven 4 also allows to skip phases (in comparison to the old graph).
+For example, it's possible to `deploy` an artifact without `install`ing it to the user repository.
+
+For compatibility, the execution behavior is not really changed by default compared to Maven 3.
+In order to actually leverage the new tree-based lifecycle, the user has to enable the concurrent builder using
+`-b concurrent`.
+Running with the concurrent builder will allow finer grained dependency instead of the usual Maven 3 per-project
+dependency.
+With the usual builders and run `mvn verify`, a project will run up to the verify phase, before a dependent project can
+start being built, whereas the concurrent builder will allow a dependant project to be built as soon as the dependencies
+are at the `ready` phase.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before:` and an `after:` phase, allowing plugins to bind themselves to those.
+For example, if you want to set up test data before running your integration tests, you could execute tasks during the
+`before:integration-test` phase.
+
+If this is not enough, perhaps because you want to do multiple things inside the same phase, you can order each
+execution inside a phase by using square brackets with an integer at the end of the phase name.
+
+Example
+
+```
+before:integration-test[100]
+before:integration-test[200]
+```
+
+**Warning**: The conceptual `pre-*` and `post-*` phases, which were only available for selected phases and had
+inconsistent naming, are deprecated.
+Don't use them!
+This becomes even more important if you are binding a plugin to the `post-*` phase of a lifecycle phase because the
+`pre-*` phase of the phase you really want to bind to does not exist, for example, binding to `process-resources` phase
+because there was no `pre-compile` phase.
+
+## Maven plugins, security, and tools
+
+### Maven plugins
+
+As mentioned above, Maven 4 contains significant code and API updates, resulting in breaking changes for (very) old
+Maven plugins that have not been updated to use the recommended APIs.
+Major changes regarding plugins include a proper immutable plugin model together with a revised plugin API.
+The updated API provides hints as preparation for Maven 4.
+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.
+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.
+
+**Advice**: If you are maintaining a Maven plugin, you should test it with Maven 3.9.x.
+Pay close attention to upcoming warnings and update the plugin accordingly.
+
+### Improved encryption
+
+Security is important, and storing unencrypted passwords is bad practice.
+Maven 3's password encryption had several serious issues and could more accurately be called "password obfuscation".
+Maven 4 instead has a completely redone encryption system, based on Maven Encryption (`mvnenc`) - a standalone CLI tool.
+As of now, it provides functionally equivalent operations as Maven 3 (see ["Maven: Password Encryption"][30]) but adds
+improvements like a `decrypt` functionality.
+A broad overview of the problems in Maven 3 and the solution in Maven 4 can be found in the
+article ["Handling sensitive data in Maven"][31] by Maven maintainer Tamás Cservenák.
+
+### Maven Resolver
+
+The [Maven Artifact Resolver][28] is a library for working with artifact repositories and dependency resolution.
+Maven 4 includes the new 2.0 release of this library, which contains more than 150 fixes, upgrades, and
+improvements, for example, a Java native HTTP-Client - thanks to raising the Java version requirement to JDK 17!
+Another major difference compared to Maven 3 is that in the new major version, the resolver is hidden behind the new
+Maven API and is no longer used directly by plugins.
Review Comment:
> This might be a good place to document the property `-Dmaven.resolver.dependencyManagerTransitivity=false`
>
> [MNG-8333 Document Maven4 transitive depMgt handling](https://issues.apache.org/jira/browse/MNG-8333)
I was thinking about this quite a time and started to change the text here, but in the end I don't want to add it, because this argument should be in a own Maven resolver guide, which also describes WHAT transitive dependency management is (including examples).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "cstamas (via GitHub)" <gi...@apache.org>.
cstamas commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894125583
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's new in Maven 4?
+
+Maven is over 20 years old and is one of the most used build-tool in the Java world.
+Since all the years one important rule was the highest backward-compatibility as possible, especially with
+its [POM-schema with Model version 4.0.0][2], used for the build itself, but also by consumers.
+This made Maven more than a tool, but a whole ecosystem with a lot of things depended on the POM, esp. the Maven Central
+repository, other build tools and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare to changes which are impossible nowadays, like a complete new build schema.
+
+Another pain point of Maven 3 is a code base with a lot of deprecated, convoluted, non performant and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebases contains old Java code that can be optimized nowadays, but also old
+dependencies and bad API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM-Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction the Model version 4.0.0 is used not only for the build, but also by consumers of the
+artifact.
+But several contents of the POM are only necessary for the build while others like the dependencies are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As names suggest the "Build-POM" will contain all information needed for to build the artifact, e.g. used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep those which are really needed to use the artifact, e.g. dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4 a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others got marked as deprecated.
+To not break the ecosystem this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as like every software update - it's suggested to update them to 4.1.0, e.g. to avoid problems when deprecated
+things get removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 till today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files the wording "Maven project" is used.
+However, project containing multiple parts, e.g. an API and a client, each of those parts was called "module" and listed
+in the `<modules>` section of the POM, leading to the terms of "multi-module project".
+This wording introduced some inconsistency, especially as projects with any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9 the term "module" raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>`analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency managing BOMs.
+While the new type is only available with model Version 4.1.0 the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2004][5].
+
+**Note**: With Maven 4 it's also possible to exclude dependencies which are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven4 importing BOMs with classifier is now possible.
+Therefore, Maven team suggests that projects BOMs be generated as classified artifacts (see Maven build "skinny" vs "
Review Comment:
So to recap:
* BOM import should happen only with POMs coming from outside of reactor (in other words "you should import only external BOMs").
* BOM creation does not matter, doing it by hand is fine as well, but generating BOMs is much more less error prone, as you "just do the usual maven stuff" and generator makes you a BOM out of it. Less typos, less room for mistakes. And, it does not becomes "tempting" to import it either :smile: Still, due to reason above, "not reusing it within reactor" means you need to manually maintain two times same information (once the versions in your build, and once in your manually crafted BOM), hence automating the BOM generations makes much more sense.
* The definition of BOM is not enforced, you can still author manually or generate whatever kind of BOM you want. We just offered this naming similar to shading (skinny vs fat).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1896756552
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicate code
Review Comment:
Removed
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1896759481
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicate code
+which costs the volunteers who maintain Maven a lot of time.
+This means that the Maven codebase contains not only old Java code that can be optimized nowadays but also old
Review Comment:
> I'm not aware of any code in Maven that can be optimized now that couldn't be optimized in Java 7 and earlier.
@khmarbaise told me several times of the last year that code was optimized first with Java 8 features, like streams etc and can be / will now be (since the vote for Java 17 has passed) further optimized with other language features like records, text blocks etc.
Passive benefits of improved GC, security updates inside the JDK etc. add to this.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1915425170
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
Review Comment:
Removed that part about security.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "slachiewicz (via GitHub)" <gi...@apache.org>.
slachiewicz commented on PR #598:
URL: https://github.com/apache/maven-site/pull/598#issuecomment-2571687387
do You have plan to publish it now or when 4 is released?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1898706117
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
Review Comment:
> delete "But this stable schema comes at a price - the lack of flexibility."
deleted
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1932454255
##########
content/site.xml:
##########
@@ -20,27 +20,27 @@ under the License.
-->
Review Comment:
Cleaned up
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "kwin (via GitHub)" <gi...@apache.org>.
kwin commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1931942972
##########
content/site.xml:
##########
@@ -20,27 +20,27 @@ under the License.
-->
Review Comment:
Please leave out unrelated formatting changes from this commit. This should be done separately.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on PR #598:
URL: https://github.com/apache/maven-site/pull/598#issuecomment-2610663987
> For this PR it should call out that the namespace used to be http://maven.apache.org/POM/4.0.0 and is now http://maven.apache.org/POM/4.1.0
Mentioned the new namespace in the Model 4.1.0 section
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894141647
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's new in Maven 4?
+
+Maven is over 20 years old and is one of the most used build-tool in the Java world.
+Since all the years one important rule was the highest backward-compatibility as possible, especially with
+its [POM-schema with Model version 4.0.0][2], used for the build itself, but also by consumers.
+This made Maven more than a tool, but a whole ecosystem with a lot of things depended on the POM, esp. the Maven Central
+repository, other build tools and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare to changes which are impossible nowadays, like a complete new build schema.
+
+Another pain point of Maven 3 is a code base with a lot of deprecated, convoluted, non performant and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebases contains old Java code that can be optimized nowadays, but also old
+dependencies and bad API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM-Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction the Model version 4.0.0 is used not only for the build, but also by consumers of the
+artifact.
+But several contents of the POM are only necessary for the build while others like the dependencies are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As names suggest the "Build-POM" will contain all information needed for to build the artifact, e.g. used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep those which are really needed to use the artifact, e.g. dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4 a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others got marked as deprecated.
+To not break the ecosystem this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as like every software update - it's suggested to update them to 4.1.0, e.g. to avoid problems when deprecated
+things get removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 till today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files the wording "Maven project" is used.
+However, project containing multiple parts, e.g. an API and a client, each of those parts was called "module" and listed
+in the `<modules>` section of the POM, leading to the terms of "multi-module project".
+This wording introduced some inconsistency, especially as projects with any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9 the term "module" raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>`analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency managing BOMs.
+While the new type is only available with model Version 4.1.0 the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2004][5].
+
+**Note**: With Maven 4 it's also possible to exclude dependencies which are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven4 importing BOMs with classifier is now possible.
+Therefore, Maven team suggests that projects BOMs be generated as classified artifacts (see Maven build "skinny" vs "
Review Comment:
Thank you for the additional info here and on Slack. I rephrased the section. Can you please check if it's a) right and b) understandable?
(I have to go for some hours, but will be back later / tomorrow morning) if anything else is needed to change here.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "elharo (via GitHub)" <gi...@apache.org>.
elharo commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1895649156
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
Review Comment:
old,
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
Review Comment:
This means that the Maven codebase contains not only old Java code that can be optimized nowadays but also old
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
Review Comment:
by the build
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
Review Comment:
I am very skeptical that Maven 4 will improve any of this. In fact I fully expect it to make the problem worse. XKCD 927 applies:
https://xkcd.com/927/
For this PR, I suggest deleting this entire paragraph. It suggest promises we're not going to keep.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
Review Comment:
duplicated -->> duplicate
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
Review Comment:
What's the impact? Explain why we want this. It's not obviously a good thing.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
Review Comment:
the consumer --> consumers
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
Review Comment:
needs a better word than "used"
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
Review Comment:
I'd be tempted to start the article here and drop the PR fluff above.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
Review Comment:
The consumer POM only contains what is necessary
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
Review Comment:
Maven generates the Consumer-POM during the build from the build POM.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
Review Comment:
This article really needs to explain the difference between build and consumers. Assume most users do not understand this, at all.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
Review Comment:
Delete the comment about IDEs
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
Review Comment:
delete "now having"
delete "already"
will only be used --> is only used by Maven
(In general, avoid future tense unless referring t0 specific dates.)
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
Review Comment:
`<modules>` element
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
Review Comment:
delete "of course"
no exclamation point
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
Review Comment:
Materials
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
Review Comment:
`<subprojects>` element
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
Review Comment:
delete "It's suggested to use"
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
Review Comment:
may or will?
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
Review Comment:
several contents --> several parts
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
Review Comment:
Properties is a big surprise. How can other projects configure these?
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
Review Comment:
extraneous closing parenthesis
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
Review Comment:
why the quotes? what's quoted?
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
Review Comment:
avoid passive voice
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
Review Comment:
which was and is still --> which is
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
Review Comment:
delete "allow the usage of a different file as the POM and"
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
Review Comment:
is also extended --> also extends
project's own
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
Review Comment:
exclamation point
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
Review Comment:
delete Of course,
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
Review Comment:
introduces --> adds
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
Review Comment:
This should be up top
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
Review Comment:
avoid passive
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
Review Comment:
run-on sentence
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
Review Comment:
I don't believe this is true
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements because you need to compile against or use another JDK, please look at
Review Comment:
"please look at" --> see
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
Review Comment:
no exclamation point
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements because you need to compile against or use another JDK, please look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was held in March 2024, shortly before Java 22 was
+released. One reason Java 17 was chosen over Java 21 was that it was (at this time) the second-last Java version for
+which many vendors offer long-term support.*
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates and even removals.
Review Comment:
delete and even removals.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements because you need to compile against or use another JDK, please look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was held in March 2024, shortly before Java 22 was
+released. One reason Java 17 was chosen over Java 21 was that it was (at this time) the second-last Java version for
+which many vendors offer long-term support.*
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates and even removals.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only the use of newer Java language features but also changes to make maintenance easier and
Review Comment:
delete the use of
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements because you need to compile against or use another JDK, please look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was held in March 2024, shortly before Java 22 was
Review Comment:
delete this note; it's not important
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
Review Comment:
This all need a better explanation with examples.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
Review Comment:
Delete this sentence.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
Review Comment:
might --> will
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
Review Comment:
exclamation point
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
Review Comment:
will they or won't they?
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
Review Comment:
That's not obvious to me
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
Review Comment:
variables or properties?
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
Review Comment:
"accessing the central repository: is incorrect
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
Review Comment:
delete anymore
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements because you need to compile against or use another JDK, please look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was held in March 2024, shortly before Java 22 was
+released. One reason Java 17 was chosen over Java 21 was that it was (at this time) the second-last Java version for
+which many vendors offer long-term support.*
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates and even removals.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only the use of newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, you should always define fixed versions of all the plugins you use!
+By doing this, you are in control of your build - at the cost of being responsible for upgrading the versions yourself.
Review Comment:
delete "- at the cost of being responsible for upgrading the versions yourself."
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements because you need to compile against or use another JDK, please look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was held in March 2024, shortly before Java 22 was
+released. One reason Java 17 was chosen over Java 21 was that it was (at this time) the second-last Java version for
+which many vendors offer long-term support.*
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates and even removals.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only the use of newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, you should always define fixed versions of all the plugins you use!
+By doing this, you are in control of your build - at the cost of being responsible for upgrading the versions yourself.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM!
Review Comment:
delete exclamation point
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements because you need to compile against or use another JDK, please look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was held in March 2024, shortly before Java 22 was
+released. One reason Java 17 was chosen over Java 21 was that it was (at this time) the second-last Java version for
+which many vendors offer long-term support.*
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates and even removals.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only the use of newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, you should always define fixed versions of all the plugins you use!
+By doing this, you are in control of your build - at the cost of being responsible for upgrading the versions yourself.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM!
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which will break the build when at least one log message
+matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, e.g., `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break; instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3, the lifecycle was literally an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more consistent execution of dependent phases, e.g., `compile` must execute after `compile-only` project
+dependencies have reached the `ready` phase, and also allows "skipping" phases (in comparison to the old graph), e.g.,
+`deploy` an artifact without `install`ing it to the user repository.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before` and `after` phase, allowing plugins to bind themselves to those by adding their
+prefixes to the name of the main phase.
+For example, if you want to set up test data before running your integration tests, you could execute tasks during the
+`before-integration-test` phase.
+
+If this is not enough, perhaps because you want to do multiple things inside the same phase, you can order each
+execution inside a phase by using square brackets with an integer at the end of the phase name, e.g.,
+
+```
+before-integration-test[100]
+before-integration-test[200]
+```
+
+**Warning**: The conceptual `pre-*` and `post-*` phases, which were only available for selected phases and had
+inconsistent naming, are deprecated - don't use them (anymore)!
+This becomes even more important if you were binding a plugin to the `post-*` phase of a lifecycle phase because the
+`pre-*` phase of the phase you really wanted to bind to did not exist, e.g., binding to `process-resources` phase
+because there was no `pre-compile` phase.
+
+## Maven plugins, security and tools
+
+### Maven plugins
+
+As mentioned above, Maven 4 will contain significant code and API updates, resulting in breaking changes for (very) old
Review Comment:
will contain --> contains
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements because you need to compile against or use another JDK, please look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was held in March 2024, shortly before Java 22 was
+released. One reason Java 17 was chosen over Java 21 was that it was (at this time) the second-last Java version for
+which many vendors offer long-term support.*
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates and even removals.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only the use of newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, you should always define fixed versions of all the plugins you use!
+By doing this, you are in control of your build - at the cost of being responsible for upgrading the versions yourself.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM!
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which will break the build when at least one log message
+matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, e.g., `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break; instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3, the lifecycle was literally an ordered list containing all phases.
Review Comment:
delete literally
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements because you need to compile against or use another JDK, please look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was held in March 2024, shortly before Java 22 was
+released. One reason Java 17 was chosen over Java 21 was that it was (at this time) the second-last Java version for
+which many vendors offer long-term support.*
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates and even removals.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only the use of newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, you should always define fixed versions of all the plugins you use!
+By doing this, you are in control of your build - at the cost of being responsible for upgrading the versions yourself.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM!
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which will break the build when at least one log message
Review Comment:
will break --> breaks
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements because you need to compile against or use another JDK, please look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was held in March 2024, shortly before Java 22 was
+released. One reason Java 17 was chosen over Java 21 was that it was (at this time) the second-last Java version for
+which many vendors offer long-term support.*
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates and even removals.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only the use of newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, you should always define fixed versions of all the plugins you use!
+By doing this, you are in control of your build - at the cost of being responsible for upgrading the versions yourself.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM!
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which will break the build when at least one log message
+matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, e.g., `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break; instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3, the lifecycle was literally an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more consistent execution of dependent phases, e.g., `compile` must execute after `compile-only` project
+dependencies have reached the `ready` phase, and also allows "skipping" phases (in comparison to the old graph), e.g.,
+`deploy` an artifact without `install`ing it to the user repository.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before` and `after` phase, allowing plugins to bind themselves to those by adding their
+prefixes to the name of the main phase.
+For example, if you want to set up test data before running your integration tests, you could execute tasks during the
+`before-integration-test` phase.
+
+If this is not enough, perhaps because you want to do multiple things inside the same phase, you can order each
+execution inside a phase by using square brackets with an integer at the end of the phase name, e.g.,
+
+```
+before-integration-test[100]
+before-integration-test[200]
+```
+
+**Warning**: The conceptual `pre-*` and `post-*` phases, which were only available for selected phases and had
+inconsistent naming, are deprecated - don't use them (anymore)!
Review Comment:
delete (anymore)!
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements because you need to compile against or use another JDK, please look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was held in March 2024, shortly before Java 22 was
+released. One reason Java 17 was chosen over Java 21 was that it was (at this time) the second-last Java version for
+which many vendors offer long-term support.*
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates and even removals.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only the use of newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, you should always define fixed versions of all the plugins you use!
+By doing this, you are in control of your build - at the cost of being responsible for upgrading the versions yourself.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM!
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which will break the build when at least one log message
+matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, e.g., `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break; instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3, the lifecycle was literally an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more consistent execution of dependent phases, e.g., `compile` must execute after `compile-only` project
+dependencies have reached the `ready` phase, and also allows "skipping" phases (in comparison to the old graph), e.g.,
+`deploy` an artifact without `install`ing it to the user repository.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before` and `after` phase, allowing plugins to bind themselves to those by adding their
+prefixes to the name of the main phase.
+For example, if you want to set up test data before running your integration tests, you could execute tasks during the
+`before-integration-test` phase.
+
+If this is not enough, perhaps because you want to do multiple things inside the same phase, you can order each
+execution inside a phase by using square brackets with an integer at the end of the phase name, e.g.,
+
+```
+before-integration-test[100]
+before-integration-test[200]
+```
+
+**Warning**: The conceptual `pre-*` and `post-*` phases, which were only available for selected phases and had
+inconsistent naming, are deprecated - don't use them (anymore)!
+This becomes even more important if you were binding a plugin to the `post-*` phase of a lifecycle phase because the
+`pre-*` phase of the phase you really wanted to bind to did not exist, e.g., binding to `process-resources` phase
+because there was no `pre-compile` phase.
+
+## Maven plugins, security and tools
+
+### Maven plugins
+
+As mentioned above, Maven 4 will contain significant code and API updates, resulting in breaking changes for (very) old
+Maven plugins that were not updated to use the recommended APIs.
+Major changes regarding plugins include a proper immutable plugin model together with a revised plugin API.
+The updated API provides hints as preparation for Maven 4.
+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.
+If a plugin still relies on long-deprecated and now removed Plexus dependency resolution, it will no longer work
Review Comment:
I'm not sure this is true. If it is, elaboration is needed.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements because you need to compile against or use another JDK, please look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was held in March 2024, shortly before Java 22 was
+released. One reason Java 17 was chosen over Java 21 was that it was (at this time) the second-last Java version for
+which many vendors offer long-term support.*
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates and even removals.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only the use of newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, you should always define fixed versions of all the plugins you use!
Review Comment:
delete "you should" and no exclamation point
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements because you need to compile against or use another JDK, please look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was held in March 2024, shortly before Java 22 was
+released. One reason Java 17 was chosen over Java 21 was that it was (at this time) the second-last Java version for
+which many vendors offer long-term support.*
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates and even removals.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only the use of newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, you should always define fixed versions of all the plugins you use!
+By doing this, you are in control of your build - at the cost of being responsible for upgrading the versions yourself.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM!
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which will break the build when at least one log message
+matches the given argument.
Review Comment:
it sounds like the message doesn't have to match, but rather the severity
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements because you need to compile against or use another JDK, please look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was held in March 2024, shortly before Java 22 was
+released. One reason Java 17 was chosen over Java 21 was that it was (at this time) the second-last Java version for
+which many vendors offer long-term support.*
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates and even removals.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only the use of newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, you should always define fixed versions of all the plugins you use!
+By doing this, you are in control of your build - at the cost of being responsible for upgrading the versions yourself.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM!
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which will break the build when at least one log message
+matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, e.g., `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break; instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3, the lifecycle was literally an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more consistent execution of dependent phases, e.g., `compile` must execute after `compile-only` project
+dependencies have reached the `ready` phase, and also allows "skipping" phases (in comparison to the old graph), e.g.,
+`deploy` an artifact without `install`ing it to the user repository.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before` and `after` phase, allowing plugins to bind themselves to those by adding their
+prefixes to the name of the main phase.
+For example, if you want to set up test data before running your integration tests, you could execute tasks during the
+`before-integration-test` phase.
+
+If this is not enough, perhaps because you want to do multiple things inside the same phase, you can order each
+execution inside a phase by using square brackets with an integer at the end of the phase name, e.g.,
+
+```
+before-integration-test[100]
+before-integration-test[200]
+```
+
+**Warning**: The conceptual `pre-*` and `post-*` phases, which were only available for selected phases and had
+inconsistent naming, are deprecated - don't use them (anymore)!
+This becomes even more important if you were binding a plugin to the `post-*` phase of a lifecycle phase because the
+`pre-*` phase of the phase you really wanted to bind to did not exist, e.g., binding to `process-resources` phase
+because there was no `pre-compile` phase.
+
+## Maven plugins, security and tools
+
+### Maven plugins
+
+As mentioned above, Maven 4 will contain significant code and API updates, resulting in breaking changes for (very) old
+Maven plugins that were not updated to use the recommended APIs.
+Major changes regarding plugins include a proper immutable plugin model together with a revised plugin API.
+The updated API provides hints as preparation for Maven 4.
+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.
+If a plugin still relies on long-deprecated and now removed Plexus dependency resolution, it will no longer work
+and needs to be updated to use JSR-330 - see [Maven & JSR-330][26] for further information.
+
+**Advice**: If you are maintaining a Maven plugin, you should test it with Maven 3.9.x, pay close attention to upcoming
Review Comment:
run-on sentence
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on PR #598:
URL: https://github.com/apache/maven-site/pull/598#issuecomment-2571696888
> do You have plan to publish it now or when 4 is released?
I would like to release it now, as a) @cstamas said we get asked what changes more often and b) several of us (e.g. Maarten, Karl Heinz, Robert, me) give talks about that quite a long time, but it's always too less time on conferences or many JUG to cover all.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "froque (via GitHub)" <gi...@apache.org>.
froque commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1926227585
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,477 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is the most widely used build tool in the Java world.
+Throughout the years, Maven has maintained backward compatibility, especially of its [POM file][2] with Model version
+4.0.0.
+
+The POM file fulfills two needs.
+First, the POM holds all the information and configuration, which are needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, for example dependencies, which are needed by projects which depend on the
+artifact.
+These dependent projects are called the "consumers".
+
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+Thus, any change in the POM's schema forces each participant of the ecosystem to either adopt the change or drop
+support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+In order for Maven to evolve, it's necessary to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## Required Java version
+
+Maven 4 requires Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 is only needed to **run Maven**!
+You can still compile against older Java versions using the same [compiler plugin configuration][6] as before.
+If you need to compile against or use another JDK, see the [Guide to Using Toolchains][7] (or the
+article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten Mulders).
+
+## POM Changes
+
+### Consumer POM
+
+Maven 4 generates a stripped down consumer POM that removes build information not needed by consumers, and deploys this
+to the remote repository.
+It does not deploy the `pom.xml` used to build the project.
+
+### Model version 4.1.0
+
+Maven 4 updates the POM version to 4.1.0.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the build POM, while the consumer POM will still use
+version 4.0.0.
+Maven generates the consumer POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 if you don't need to use the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project built with Maven.
+The [top level directory][32] of a Maven project contains at least the source folder `src` and the project's POM file
+`pom.xml`.
+A Maven project may have other Maven projects within subdirectories, each with its own `pom.xml` file.
+Each project within a subdirectory is called a "subproject".
+
+Example: Project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects unless they are linked from the root POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+Projects which have at least one subproject are called "multi-module projects", while those which do not have any
+subprojects are called "single module projects".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated `bom` packaging type to provide a [Bill of Materials BOM][4].
+This now differentiates between parent POMs and dependency-managing BOMs.
+The new type is only available as a build POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible consumer POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build.
+In other words: you should only import external BOMs.
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing build POM and consumer POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "consumer POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, for example plugin configuration!
+* Some of the build-related content which is (as of now) still available in the consumer POM might be available only in
+ the build POM in the future.
+
+| Content | Build POM | Consumer POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a consumer POM based on version 4.1.0, for example
+when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, for example a `maven.config` or
+`jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the build POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, for example when you want to define the path to a `checkstyle-suppressions.xml`
+file for the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+current working directory.
+The `rootDirectory` can only contain a value when either a `.mvn` directory is defined or the `root` attribute is set to
+true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4 those properties were removed or marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 consumer POM is set in stone, the build POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, like `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration.
+
+Example
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, for example `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects can cause confusion in Maven 3.
+When the build of subproject B, which requires subproject A, is failing for whatever reason, Maven 3 is telling
+the user to fix the error and then resume the build with `--resume-from :<nameOfTheFailingSubproject>`.
+But doing this instantly fails the build again, because the required subproject A couldn't be found (as it was not
+rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (for example Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where successfully
+built subprojects were deployed to the (local or remote) repository, but failed subprojects were not.
+This was finally changed in Maven 4 to what most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+in Maven 3, for example using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, always define fixed versions of all the plugins you use.
+By doing this, you are in control of your build.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM.
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which breaks the build when the severity of at least one log
+message matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, for example, `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break.
+Instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+In Maven 3 the lifecycle is an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more fine-grained execution of dependent phases.
+For example, the `compile` phase must execute after `compile-only` project dependencies have reached the `ready` phase.
+Maven 4 also allows to skip phases (in comparison to the old graph).
+For example, it's possible to `deploy` an artifact without `install`ing it to the user repository.
+
+For compatibility, the execution behavior is not really changed by default compared to Maven 3.
+In order to actually leverage the new tree-based lifecycle, the user has to enable the concurrent builder using
+`-b concurrent`.
+Running with the concurrent builder will allow finer grained dependency instead of the usual Maven 3 per-project
+dependency.
+With the usual builders and run `mvn verify`, a project will run up to the verify phase, before a dependent project can
+start being built, whereas the concurrent builder will allow a dependant project to be built as soon as the dependencies
+are at the `ready` phase.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before:` and an `after:` phase, allowing plugins to bind themselves to those.
+For example, if you want to set up test data before running your integration tests, you could execute tasks during the
+`before:integration-test` phase.
+
+If this is not enough, perhaps because you want to do multiple things inside the same phase, you can order each
+execution inside a phase by using square brackets with an integer at the end of the phase name.
+
+Example
+
+```
+before:integration-test[100]
+before:integration-test[200]
+```
+
+**Warning**: The conceptual `pre-*` and `post-*` phases, which were only available for selected phases and had
+inconsistent naming, are deprecated.
+Don't use them!
+This becomes even more important if you are binding a plugin to the `post-*` phase of a lifecycle phase because the
+`pre-*` phase of the phase you really want to bind to does not exist, for example, binding to `process-resources` phase
+because there was no `pre-compile` phase.
+
+## Maven plugins, security, and tools
+
+### Maven plugins
+
+As mentioned above, Maven 4 contains significant code and API updates, resulting in breaking changes for (very) old
+Maven plugins that have not been updated to use the recommended APIs.
+Major changes regarding plugins include a proper immutable plugin model together with a revised plugin API.
+The updated API provides hints as preparation for Maven 4.
+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.
+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.
+
+**Advice**: If you are maintaining a Maven plugin, you should test it with Maven 3.9.x.
+Pay close attention to upcoming warnings and update the plugin accordingly.
+
+### Improved encryption
+
+Security is important, and storing unencrypted passwords is bad practice.
+Maven 3's password encryption had several serious issues and could more accurately be called "password obfuscation".
+Maven 4 instead has a completely redone encryption system, based on Maven Encryption (`mvnenc`) - a standalone CLI tool.
+As of now, it provides functionally equivalent operations as Maven 3 (see ["Maven: Password Encryption"][30]) but adds
+improvements like a `decrypt` functionality.
+A broad overview of the problems in Maven 3 and the solution in Maven 4 can be found in the
+article ["Handling sensitive data in Maven"][31] by Maven maintainer Tamás Cservenák.
+
+### Maven Resolver
+
+The [Maven Artifact Resolver][28] is a library for working with artifact repositories and dependency resolution.
+Maven 4 includes the new 2.0 release of this library, which contains more than 150 fixes, upgrades, and
+improvements, for example, a Java native HTTP-Client - thanks to raising the Java version requirement to JDK 17!
+Another major difference compared to Maven 3 is that in the new major version, the resolver is hidden behind the new
+Maven API and is no longer used directly by plugins.
Review Comment:
This might be a good place to document the property `-Dmaven.resolver.dependencyManagerTransitivity=false`
[MNG-8333 Document Maven4 transitive depMgt handling](https://issues.apache.org/jira/browse/MNG-8333)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on PR #598:
URL: https://github.com/apache/maven-site/pull/598#issuecomment-2590876362
Spend a few hours to update introduction. Hope that it meets the requirements of Maven now.
Will now wait for a second review by @gnodet and explanation from @elharo about two of his comments I did not understand.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1921023562
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,465 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
Review Comment:
I rephrased the section and added example. However I left out a `groupId` in this, because it's not needed. Maven will build subprojects as long as they are listed as such (and existent ofc), but a subproject does not need to have the same `groupId` or have the higher project configured as parent (verified with Maven 4 RC2)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1932453109
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,477 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is the most widely used build tool in the Java world.
+Throughout the years, Maven has maintained backward compatibility, especially of its [POM file][2] with Model version
+4.0.0.
+
+The POM file fulfills two needs.
+First, the POM holds all the information and configuration, which are needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, for example dependencies, which are needed by projects which depend on the
+artifact.
+These dependent projects are called the "consumers".
+
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+Thus, any change in the POM's schema forces each participant of the ecosystem to either adopt the change or drop
+support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+In order for Maven to evolve, it's necessary to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## Required Java version
+
+Maven 4 requires Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
Review Comment:
Changed to end the sentence after "improvements".
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "lbruun (via GitHub)" <gi...@apache.org>.
lbruun commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1939154487
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,476 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is the most widely used build tool in the Java world.
+Throughout the years, Maven has maintained backward compatibility, especially of its [POM file][2] with Model version
+4.0.0.
+
+The POM file fulfills two needs.
+First, the POM holds all the information and configuration, which are needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, for example dependencies, which are needed by projects which depend on the
+artifact.
+These dependent projects are called the "consumers".
+
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+Thus, any change in the POM's schema forces each participant of the ecosystem to either adopt the change or drop
+support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+In order for Maven to evolve, it's necessary to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## Required Java version
+
+Maven 4 requires Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements.
+
+**Important note**: Java 17 is only needed to **run Maven**!
+You can still compile against older Java versions using the same [compiler plugin configuration][6] as before.
+If you need to compile against or use another JDK, see the [Guide to Using Toolchains][7] (or the
+article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten Mulders).
+
+## POM Changes
+
+### Consumer POM
+
+Maven 4 generates a stripped down consumer POM that removes build information not needed by consumers, and deploys this
+to the remote repository.
+It does not deploy the `pom.xml` used to build the project.
+
+### Model version 4.1.0
+
+Maven 4 updates the POM version to 4.1.0 which defines the namespace `http://maven.apache.org/POM/4.1.0`.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the build POM, while the consumer POM will still use
+version 4.0.0.
+Maven generates the consumer POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 if you don't need to use the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project built with Maven.
+The [top level directory][32] of a Maven project contains at least the source folder `src` and the project's POM file
+`pom.xml`.
+A Maven project may have other Maven projects within subdirectories, each with its own `pom.xml` file.
+Each project within a subdirectory is called a "subproject".
+
+Example: Project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects unless they are linked from the root POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+Projects which have at least one subproject are called "multi-module projects", while those which do not have any
+subprojects are called "single module projects".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated `bom` packaging type to provide a [Bill of Materials BOM][4].
+This now differentiates between parent POMs and dependency-managing BOMs.
+The new type is only available as a build POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible consumer POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build.
+In other words: you should only import external BOMs.
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing build POM and consumer POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "consumer POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, for example plugin configuration!
+* Some of the build-related content which is (as of now) still available in the consumer POM might be available only in
+ the build POM in the future.
+
+| Content | Build POM | Consumer POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a consumer POM based on version 4.1.0, for example
+when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, for example a `maven.config` or
+`jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the build POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, for example when you want to define the path to a `checkstyle-suppressions.xml`
+file for the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+current working directory.
+The `rootDirectory` can only contain a value when either a `.mvn` directory is defined or the `root` attribute is set to
+true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4 those properties were removed or marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 consumer POM is set in stone, the build POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, like `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration.
+
+Example
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, for example `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects can cause confusion in Maven 3.
+When the build of subproject B, which requires subproject A, is failing for whatever reason, Maven 3 is telling
+the user to fix the error and then resume the build with `--resume-from :<nameOfTheFailingSubproject>`.
+But doing this instantly fails the build again, because the required subproject A couldn't be found (as it was not
+rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (for example Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where successfully
Review Comment:
### Regarding "atomic deploy"
Explain how this relates to the `deployAtEnd` property ([LINK](https://maven.apache.org/plugins/maven-deploy-plugin/deploy-mojo.html)) which exists in Maven 3 too.
So this was also possible with Maven 3, right? Is it to be understood that in Maven v4 it is no longer necessary to explicitly set `-DdeployAtEnd=true` as we do with Maven v3 ?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "mthmulders (via GitHub)" <gi...@apache.org>.
mthmulders commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1965446022
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,476 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is the most widely used build tool in the Java world.
+Throughout the years, Maven has maintained backward compatibility, especially of its [POM file][2] with Model version
+4.0.0.
+
+The POM file fulfills two needs.
+First, the POM holds all the information and configuration, which are needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, for example dependencies, which are needed by projects which depend on the
+artifact.
+These dependent projects are called the "consumers".
+
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+Thus, any change in the POM's schema forces each participant of the ecosystem to either adopt the change or drop
+support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+In order for Maven to evolve, it's necessary to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## Required Java version
+
+The required Java version to run Maven 4 is Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 is only needed to **run Maven**!
+You can still compile against older Java versions using the same [compiler plugin configuration][6] as before.
+If you need to compile against or use another JDK, see the [Guide to Using Toolchains][7] (or the
+article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten Mulders).
+
+## POM Changes
+
+### Build POM and consumer POM
+
+In Maven 3 both the build and consumers use the same POM file with model version 4.0.0.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a build POM and a consumer POM.
+As the names suggest, the build POM contains all information needed to build the artifact, for example applied plugins
+and their configuration, while the consumer POM, which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, for example dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the build POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the build POM, while the consumer POM will still use
+version 4.0.0.
+Maven generates the consumer POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 if you don't need to use the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project built with Maven.
+The [root directory][32] of a Maven project contains at least the source folder `src` and the project's POM file
+`pom.xml`.
+A Maven project may have other Maven projects within subdirectories, each with its own `pom.xml` file.
+Each project within a subdirectory is called a "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects unless they are linked from the root POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+Projects which have at least one subproject are called "multi-module projects", while those which have any subprojects
+are called "single module projects".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated `bom` packaging type to provide a [Bill of Materials BOM][4].
+This now differentiates between parent POMs and dependency-managing BOMs.
+The new type is only available as a build POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible consumer POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build.
+In other words: you should only import external BOMs.
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing build POM and consumer POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "consumer POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, for example plugin configuration!
+* Some of the build-related content which is (as of now) still available in the consumer POM might be available only in
+ the build POM in the future.
+
+| Content | Build POM | Consumer POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a consumer POM based on version 4.1.0, for example
+when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, for example a `maven.config` or
+`jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the build POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, for example when you want to define the path to a `checkstyle-suppressions.xml`
+file for the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+current working directory.
Review Comment:
AFAIK, "session" is the execution of Maven, not the current working directory.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "mthmulders (via GitHub)" <gi...@apache.org>.
mthmulders commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1965452443
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,476 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
Review Comment:
Pending the discussion on namespace changes, I would suggest _not_ to include "inference of `modelVersion` from namespace".
Because the discussion in [MNG-8537](https://issues.apache.org/jira/browse/MNG-8537) has no conclusion yet, it is not (yet) a given that the namespace change will make it into Maven 4. If we publish a page that says it will be part of Maven 4, people will expect it to happen.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "gnodet (via GitHub)" <gi...@apache.org>.
gnodet commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894641014
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -390,6 +390,15 @@ improvements, e.g., a Java native HTTP-Client - thanks to raising the Java versi
Another major difference compared to Maven 3 is that in the new major version, the resolver is hidden behind the new
Maven API and is no longer used directly by plugins.
+### Maven Shell
+
+When you run any `mvn` command, the full chain of booting Java, Maven, load config, do the work, tear down and exit the
+process is done - **every single time**.
+To improve performance and reduce build time, you can use the [Maven Daemon][29] (`mvnd`), which manages a pool of N
+resident Maven processes.
+With Maven 4 you can also use the brightly polished "Maven Shell" (`mvnsh`), which will keep exactly one resident Maven
+process as long as the shell is opened.
Review Comment:
```
### Maven Shell
Each time you run an `mvn` command, the entire process chain is executed: booting Java, starting Maven, loading the configuration, performing the task, tearing down, and exiting — **every single time**.
To improve performance and reduce build times, you can use the [Maven Daemon][29] (`mvnd`), which manages a pool of resident Maven processes.
With Maven 4, you can also take advantage of the newly defined "Maven Shell" (`mvnsh`), which keeps a single Maven process running for as long as the shell remains open.
```
Minor improvements to this section.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1915409432
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
Review Comment:
Decided to drop those lines.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1915412665
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
Review Comment:
Updated in next push.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
Review Comment:
Updated in next push.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "lbruun (via GitHub)" <gi...@apache.org>.
lbruun commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1939161073
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,476 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
Review Comment:
Inference of `<modelVersion>` is another new feature in Maven v4. You may want to add that.
Doing
```xml
<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.1.0 https://maven.apache.org/xsd/maven-4.1.0.xsd">
<modelVersion>4.1.0</modelVersion>
</project>
```
is no longer necessary: you can leave out the `<modelVersion>` element and it will be inferred from the XML ns.
```xml
<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.1.0 https://maven.apache.org/xsd/maven-4.1.0.xsd">
</project>
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "lbruun (via GitHub)" <gi...@apache.org>.
lbruun commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1939161073
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,476 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
Review Comment:
Inference of `<modelVersion>` is another new feature in Maven v4. You may want to add that.
Doing
```xml
<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.1.0 https://maven.apache.org/xsd/maven-4.1.0.xsd">
<modelVersion>4.1.0</modelVersion>
</project>
```
is no longer necessary: you can leave out the `<modelVersion>` element and it will be inferred from the XML ns.
The below is equivalent to the above:
```xml
<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.1.0 https://maven.apache.org/xsd/maven-4.1.0.xsd">
</project>
```
(no `<modelVersion>` element)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1895719119
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements because you need to compile against or use another JDK, please look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was held in March 2024, shortly before Java 22 was
+released. One reason Java 17 was chosen over Java 21 was that it was (at this time) the second-last Java version for
+which many vendors offer long-term support.*
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates and even removals.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only the use of newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, you should always define fixed versions of all the plugins you use!
+By doing this, you are in control of your build - at the cost of being responsible for upgrading the versions yourself.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM!
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which will break the build when at least one log message
+matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, e.g., `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break; instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3, the lifecycle was literally an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more consistent execution of dependent phases, e.g., `compile` must execute after `compile-only` project
+dependencies have reached the `ready` phase, and also allows "skipping" phases (in comparison to the old graph), e.g.,
+`deploy` an artifact without `install`ing it to the user repository.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before` and `after` phase, allowing plugins to bind themselves to those by adding their
+prefixes to the name of the main phase.
+For example, if you want to set up test data before running your integration tests, you could execute tasks during the
+`before-integration-test` phase.
+
+If this is not enough, perhaps because you want to do multiple things inside the same phase, you can order each
+execution inside a phase by using square brackets with an integer at the end of the phase name, e.g.,
+
+```
+before-integration-test[100]
+before-integration-test[200]
+```
+
+**Warning**: The conceptual `pre-*` and `post-*` phases, which were only available for selected phases and had
+inconsistent naming, are deprecated - don't use them (anymore)!
+This becomes even more important if you were binding a plugin to the `post-*` phase of a lifecycle phase because the
+`pre-*` phase of the phase you really wanted to bind to did not exist, e.g., binding to `process-resources` phase
+because there was no `pre-compile` phase.
+
+## Maven plugins, security and tools
+
+### Maven plugins
+
+As mentioned above, Maven 4 will contain significant code and API updates, resulting in breaking changes for (very) old
+Maven plugins that were not updated to use the recommended APIs.
+Major changes regarding plugins include a proper immutable plugin model together with a revised plugin API.
+The updated API provides hints as preparation for Maven 4.
+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.
+If a plugin still relies on long-deprecated and now removed Plexus dependency resolution, it will no longer work
Review Comment:
> I'm not sure this is true. If it is, elaboration is needed.
@cstamas @gnodet Can you give us some insight please?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1898722228
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
Review Comment:
> This should be up top
I understand what you mean.
Let me show you my thoughts why this changes is mentioned "so late": I decided to start with POM changes, because I think the introduction of the Build-POM/Consumer-POM is the biggest motivation for Maven 4 (as written in the introduction) and the most meaningful change of all.
POM changes also effect the renamed subprojects, which lead to the chapter about those. And then workflow, lifecyle, runtime with Java 17 as the most important in this category.
I was thinking about pulling the Java 17 change out of this, but decided against it, so this whole chapter reads a bit more well-rounded (not sure if this is the correct English word). I think the current structure contains a good "central thread / dramatic line" (again not sure if this is a proper translation, closest I found in the dictionary).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on PR #598:
URL: https://github.com/apache/maven-site/pull/598#issuecomment-2564055841
@elharo Thanks for your feedback again. I don't know why I have not seen it 4 days ago :O Think I went through all of them, except the subproject renaming. Might have another look at it tomorrow (I'm too tired for that now).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "cstamas (via GitHub)" <gi...@apache.org>.
cstamas commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894104074
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's new in Maven 4?
+
+Maven is over 20 years old and is one of the most used build-tool in the Java world.
+Since all the years one important rule was the highest backward-compatibility as possible, especially with
+its [POM-schema with Model version 4.0.0][2], used for the build itself, but also by consumers.
+This made Maven more than a tool, but a whole ecosystem with a lot of things depended on the POM, esp. the Maven Central
+repository, other build tools and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare to changes which are impossible nowadays, like a complete new build schema.
+
+Another pain point of Maven 3 is a code base with a lot of deprecated, convoluted, non performant and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebases contains old Java code that can be optimized nowadays, but also old
+dependencies and bad API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM-Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction the Model version 4.0.0 is used not only for the build, but also by consumers of the
+artifact.
+But several contents of the POM are only necessary for the build while others like the dependencies are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As names suggest the "Build-POM" will contain all information needed for to build the artifact, e.g. used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep those which are really needed to use the artifact, e.g. dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4 a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others got marked as deprecated.
+To not break the ecosystem this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as like every software update - it's suggested to update them to 4.1.0, e.g. to avoid problems when deprecated
+things get removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 till today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files the wording "Maven project" is used.
+However, project containing multiple parts, e.g. an API and a client, each of those parts was called "module" and listed
+in the `<modules>` section of the POM, leading to the terms of "multi-module project".
+This wording introduced some inconsistency, especially as projects with any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9 the term "module" raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>`analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency managing BOMs.
+While the new type is only available with model Version 4.1.0 the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2004][5].
+
+**Note**: With Maven 4 it's also possible to exclude dependencies which are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven4 importing BOMs with classifier is now possible.
+Therefore, Maven team suggests that projects BOMs be generated as classified artifacts (see Maven build "skinny" vs "
Review Comment:
Our stance (@gnodet could chime in when online) is following: BOMs should be _generated_ and not used within reactor (see issues), because users are "tempted" to create BOMs within reactor (is fine, as long BOM is "published only"), and then reuse BOM in same way as any external BOM would be reused: by importing within reactor. But, importing within reactor causes "build peculiarities" usually unexpected to users. Hence, we think that _generating BOMs_ simply prevents the two issues, as reactor dependendencies should be managed using inheritance, as it was always the case with Maven. Appearance of BOMs simply caused this "boost of creativity", to reuse them within reactor, but also publish them to downstream users, and it is wrong. Hence, Maven 4 shows an "example", and generates it's own BOMs. Related https://issues.apache.org/jira/browse/MNG-8012 and https://issues.apache.org/jira/browse/MNG-8009
In short: only external BOMs should be imported to reactor.
As per "what is a BOM", there is a split among us as can be seen in this old PR: https://github.com/apache/maven/pull/689
In short, for some, "[BOM represents only the set of modules of a multimodule](https://github.com/apache/maven/pull/689#issuecomment-1061640064)" (only the reactor, so to say) while for others (@gnodet and me included) "BOM is bill of materials", so full stack (if I do an extension for Maven version X, I want same version of resolver, logging, Sisu etc as well... Similarly, look at all our plugins: after version property defining Maven version that plugins builds against, property is usually followed by a section with bunch of "keep in lockstep with Maven" version properties for logging, resolver, etc). Hence, the "skinny" (first definition) vs "fat" (second definition). In fact, Maven4 generates both now, so pleases both parties.
Of cource, Maven 4 build generated BOMs can be used only in Maven 4 builds, as Maven 4 allows importing BOMs with classifiers... So for Maven3, this is still an issue.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1898709977
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
Review Comment:
> extraneous closing parenthesis
I don't think so, the opening is at the end of the line above (but line break at 120 chars)
> (as shown in [MNG-8009][32])
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1898709642
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
Review Comment:
"may", as it's not 100%, but chances are good - that's how I understood the linked issue and what Tamas said to me.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "elharo (via GitHub)" <gi...@apache.org>.
elharo commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1932090146
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,477 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is the most widely used build tool in the Java world.
+Throughout the years, Maven has maintained backward compatibility, especially of its [POM file][2] with Model version
+4.0.0.
+
+The POM file fulfills two needs.
+First, the POM holds all the information and configuration, which are needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, for example dependencies, which are needed by projects which depend on the
+artifact.
+These dependent projects are called the "consumers".
+
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+Thus, any change in the POM's schema forces each participant of the ecosystem to either adopt the change or drop
+support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+In order for Maven to evolve, it's necessary to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## Required Java version
+
+Maven 4 requires Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 is only needed to **run Maven**!
+You can still compile against older Java versions using the same [compiler plugin configuration][6] as before.
+If you need to compile against or use another JDK, see the [Guide to Using Toolchains][7] (or the
+article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten Mulders).
+
+## POM Changes
+
+### Consumer POM
+
+Maven 4 generates a stripped down consumer POM that removes build information not needed by consumers, and deploys this
+to the remote repository.
+It does not deploy the `pom.xml` used to build the project.
+
+### Model version 4.1.0
+
+Maven 4 updates the POM version to 4.1.0 which defines the namespace `http://maven.apache.org/POM/4.1.0`.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the build POM, while the consumer POM will still use
+version 4.0.0.
+Maven generates the consumer POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 if you don't need to use the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project built with Maven.
+The [top level directory][32] of a Maven project contains at least the source folder `src` and the project's POM file
+`pom.xml`.
+A Maven project may have other Maven projects within subdirectories, each with its own `pom.xml` file.
+Each project within a subdirectory is called a "subproject".
+
+Example: Project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects unless they are linked from the root POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+Projects which have at least one subproject are called "multi-module projects", while those which do not have any
+subprojects are called "single module projects".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated `bom` packaging type to provide a [Bill of Materials BOM][4].
+This now differentiates between parent POMs and dependency-managing BOMs.
+The new type is only available as a build POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible consumer POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build.
+In other words: you should only import external BOMs.
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing build POM and consumer POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "consumer POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, for example plugin configuration!
+* Some of the build-related content which is (as of now) still available in the consumer POM might be available only in
+ the build POM in the future.
+
+| Content | Build POM | Consumer POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a consumer POM based on version 4.1.0, for example
+when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, for example a `maven.config` or
+`jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the build POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, for example when you want to define the path to a `checkstyle-suppressions.xml`
+file for the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+current working directory.
+The `rootDirectory` can only contain a value when either a `.mvn` directory is defined or the `root` attribute is set to
+true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4 those properties were removed or marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 consumer POM is set in stone, the build POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, like `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration.
+
+Example
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, for example `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects can cause confusion in Maven 3.
+When the build of subproject B, which requires subproject A, is failing for whatever reason, Maven 3 is telling
+the user to fix the error and then resume the build with `--resume-from :<nameOfTheFailingSubproject>`.
+But doing this instantly fails the build again, because the required subproject A couldn't be found (as it was not
+rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (for example Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where successfully
+built subprojects were deployed to the (local or remote) repository, but failed subprojects were not.
+This was finally changed in Maven 4 to what most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+in Maven 3, for example using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, always define fixed versions of all the plugins you use.
+By doing this, you are in control of your build.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM.
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which breaks the build when the severity of at least one log
+message matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, for example, `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break.
+Instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+In Maven 3 the lifecycle is an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more fine-grained execution of dependent phases.
+For example, the `compile` phase must execute after `compile-only` project dependencies have reached the `ready` phase.
+Maven 4 also allows to skip phases (in comparison to the old graph).
+For example, it's possible to `deploy` an artifact without `install`ing it to the user repository.
+
+For compatibility, the execution behavior is not really changed by default compared to Maven 3.
+In order to actually leverage the new tree-based lifecycle, the user has to enable the concurrent builder using
+`-b concurrent`.
+Running with the concurrent builder will allow finer grained dependency instead of the usual Maven 3 per-project
+dependency.
+With the usual builders and run `mvn verify`, a project will run up to the verify phase, before a dependent project can
+start being built, whereas the concurrent builder will allow a dependant project to be built as soon as the dependencies
+are at the `ready` phase.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before:` and an `after:` phase, allowing plugins to bind themselves to those.
+For example, if you want to set up test data before running your integration tests, you could execute tasks during the
+`before:integration-test` phase.
+
+If this is not enough, perhaps because you want to do multiple things inside the same phase, you can order each
+execution inside a phase by using square brackets with an integer at the end of the phase name.
+
+Example
+
+```
+before:integration-test[100]
+before:integration-test[200]
+```
+
+**Warning**: The conceptual `pre-*` and `post-*` phases, which were only available for selected phases and had
+inconsistent naming, are deprecated.
+Don't use them!
+This becomes even more important if you are binding a plugin to the `post-*` phase of a lifecycle phase because the
+`pre-*` phase of the phase you really want to bind to does not exist, for example, binding to `process-resources` phase
+because there was no `pre-compile` phase.
+
+## Maven plugins, security, and tools
+
+### Maven plugins
+
+As mentioned above, Maven 4 contains significant code and API updates, resulting in breaking changes for (very) old
+Maven plugins that have not been updated to use the recommended APIs.
+Major changes regarding plugins include a proper immutable plugin model together with a revised plugin API.
+The updated API provides hints as preparation for Maven 4.
+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.
+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.
+
+**Advice**: If you are maintaining a Maven plugin, you should test it with Maven 3.9.x.
+Pay close attention to upcoming warnings and update the plugin accordingly.
+
+### Improved encryption
+
+Security is important, and storing unencrypted passwords is bad practice.
+Maven 3's password encryption had several serious issues and could more accurately be called "password obfuscation".
+Maven 4 instead has a completely redone encryption system, based on Maven Encryption (`mvnenc`) - a standalone CLI tool.
Review Comment:
"plexus-sec-dispatcher is NOT an API, is not something people should use or reuse or even made aware. " -- Hyrum's Law rides again
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1917016737
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
Review Comment:
> Are these Java system properties?
Hm thought it is clear that this section is about POM properties. Do you think "POM properties" is clearer or maybe "Propertiy definitions used in the POM"?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "cstamas (via GitHub)" <gi...@apache.org>.
cstamas commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894104074
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's new in Maven 4?
+
+Maven is over 20 years old and is one of the most used build-tool in the Java world.
+Since all the years one important rule was the highest backward-compatibility as possible, especially with
+its [POM-schema with Model version 4.0.0][2], used for the build itself, but also by consumers.
+This made Maven more than a tool, but a whole ecosystem with a lot of things depended on the POM, esp. the Maven Central
+repository, other build tools and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare to changes which are impossible nowadays, like a complete new build schema.
+
+Another pain point of Maven 3 is a code base with a lot of deprecated, convoluted, non performant and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebases contains old Java code that can be optimized nowadays, but also old
+dependencies and bad API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM-Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction the Model version 4.0.0 is used not only for the build, but also by consumers of the
+artifact.
+But several contents of the POM are only necessary for the build while others like the dependencies are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As names suggest the "Build-POM" will contain all information needed for to build the artifact, e.g. used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep those which are really needed to use the artifact, e.g. dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4 a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others got marked as deprecated.
+To not break the ecosystem this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as like every software update - it's suggested to update them to 4.1.0, e.g. to avoid problems when deprecated
+things get removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 till today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files the wording "Maven project" is used.
+However, project containing multiple parts, e.g. an API and a client, each of those parts was called "module" and listed
+in the `<modules>` section of the POM, leading to the terms of "multi-module project".
+This wording introduced some inconsistency, especially as projects with any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9 the term "module" raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>`analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency managing BOMs.
+While the new type is only available with model Version 4.1.0 the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2004][5].
+
+**Note**: With Maven 4 it's also possible to exclude dependencies which are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven4 importing BOMs with classifier is now possible.
+Therefore, Maven team suggests that projects BOMs be generated as classified artifacts (see Maven build "skinny" vs "
Review Comment:
Our stance (@gnodet could chime in when online) is following: BOMs should be _generated_ and not used within reactor (see issues), because users are "tempted" to create BOMs within reactor (is fine, as long BOM is "published only"), and then reuse BOM in same way as any external BOM would be reused: by importing within reactor. But, importing within reactor causes "build peculiarities" usually unexpected to users. Hence, we think that _generating BOMs_ simply prevents the two issues, as reactor dependendencies should be managed using inheritance, as it was always the case with Maven. Appearance of BOMs simply caused this "boost of creativity", to reuse them within reactor, but also publish them to downstream users, and it is wrong. Hence, Maven 4 shows an "example", and generates it's own BOMs. Related https://issues.apache.org/jira/browse/MNG-8012 and https://issues.apache.org/jira/browse/MNG-8009
In short: only external BOMs should be imported to reactor.
As per "what is a BOM", there is a split among us as can be seen in this old PR: https://github.com/apache/maven/pull/689
In short, for some, "[BOM represents only the set of modules of a multimodule](https://github.com/apache/maven/pull/689#issuecomment-1061640064)" (only the reactor, so to say) while for others (@gnodet and me included) "BOM is bill of materials", so full stack (if I do an extension for Maven version X, I want same version of resolver, logging, Sisu etc as well... Similarly, look at all our plugins: after version property defining Maven version that plugins builds against, property is usually followed by a section with bunch of "keep in lockstep with Maven" version properties for logging, resolver, etc). Hence, the "skinny" (first definition) vs "fat" (second definition). In fact, Maven4 generates both now, so pleases both parties.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1895723846
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
Review Comment:
What I want to express with that, that the Maven codebase and API got a lot of updates and improvements. It should not be a promise, but a note about this. If we don't do any more updates - the sentence in the notes stays true - the team did put a lot of effort into updates. Do you have another suggestion to phrase this thought of mine?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1895761241
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicate code
+which costs the volunteers who maintain Maven a lot of time.
+This means that the Maven codebase contains not only old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only by the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements because you need to compile against or use another JDK, please look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was held in March 2024, shortly before Java 22 was
+released. One reason Java 17 was chosen over Java 21 was that it was (at this time) the second-last Java version for
+which many vendors offer long-term support.*
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates and even removals.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only the use of newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, you should always define fixed versions of all the plugins you use!
+By doing this, you are in control of your build - at the cost of being responsible for upgrading the versions yourself.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM!
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which will break the build when at least one log message
+matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, e.g., `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break; instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3, the lifecycle was an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more consistent execution of dependent phases, e.g., `compile` must execute after `compile-only` project
+dependencies have reached the `ready` phase, and also allows "skipping" phases (in comparison to the old graph), e.g.,
+`deploy` an artifact without `install`ing it to the user repository.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before` and `after` phase, allowing plugins to bind themselves to those by adding their
+prefixes to the name of the main phase.
+For example, if you want to set up test data before running your integration tests, you could execute tasks during the
+`before-integration-test` phase.
+
+If this is not enough, perhaps because you want to do multiple things inside the same phase, you can order each
+execution inside a phase by using square brackets with an integer at the end of the phase name, e.g.,
+
+```
+before-integration-test[100]
+before-integration-test[200]
+```
+
+**Warning**: The conceptual `pre-*` and `post-*` phases, which were only available for selected phases and had
+inconsistent naming, are deprecated - don't use them!
+This becomes even more important if you were binding a plugin to the `post-*` phase of a lifecycle phase because the
+`pre-*` phase of the phase you really wanted to bind to did not exist, e.g., binding to `process-resources` phase
+because there was no `pre-compile` phase.
+
+## Maven plugins, security and tools
+
+### Maven plugins
+
+As mentioned above, Maven 4 contains significant code and API updates, resulting in breaking changes for (very) old
+Maven plugins that were not updated to use the recommended APIs.
+Major changes regarding plugins include a proper immutable plugin model together with a revised plugin API.
+The updated API provides hints as preparation for Maven 4.
+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.
+If a plugin still relies on long-deprecated and now removed Plexus dependency resolution, it will no longer work.
Review Comment:
Updated
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1896754735
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
Review Comment:
> Maven 4 does not seem to have improved in this regard.
I agree on this, but I think that's not the direct, but only an indirect goal of Maven 4 as stated in the line below he quote:
> Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
As this is what's needed: Seperate build-pom from consumer one. So maven can do what ever it wants do to without breaking the ecosystem.
May I ask how you would phrase the introduction of the article to point out the "same POM-problem?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "cstamas (via GitHub)" <gi...@apache.org>.
cstamas commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894104074
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's new in Maven 4?
+
+Maven is over 20 years old and is one of the most used build-tool in the Java world.
+Since all the years one important rule was the highest backward-compatibility as possible, especially with
+its [POM-schema with Model version 4.0.0][2], used for the build itself, but also by consumers.
+This made Maven more than a tool, but a whole ecosystem with a lot of things depended on the POM, esp. the Maven Central
+repository, other build tools and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare to changes which are impossible nowadays, like a complete new build schema.
+
+Another pain point of Maven 3 is a code base with a lot of deprecated, convoluted, non performant and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebases contains old Java code that can be optimized nowadays, but also old
+dependencies and bad API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM-Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction the Model version 4.0.0 is used not only for the build, but also by consumers of the
+artifact.
+But several contents of the POM are only necessary for the build while others like the dependencies are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As names suggest the "Build-POM" will contain all information needed for to build the artifact, e.g. used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep those which are really needed to use the artifact, e.g. dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4 a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others got marked as deprecated.
+To not break the ecosystem this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as like every software update - it's suggested to update them to 4.1.0, e.g. to avoid problems when deprecated
+things get removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 till today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files the wording "Maven project" is used.
+However, project containing multiple parts, e.g. an API and a client, each of those parts was called "module" and listed
+in the `<modules>` section of the POM, leading to the terms of "multi-module project".
+This wording introduced some inconsistency, especially as projects with any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9 the term "module" raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>`analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency managing BOMs.
+While the new type is only available with model Version 4.1.0 the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2004][5].
+
+**Note**: With Maven 4 it's also possible to exclude dependencies which are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven4 importing BOMs with classifier is now possible.
+Therefore, Maven team suggests that projects BOMs be generated as classified artifacts (see Maven build "skinny" vs "
Review Comment:
Our stance (@gnodet could chime in when online) is following: BOMs should be _generated_ and not used within reactor (see issues), because users are "tempted" to create BOMs within reactor (is fine, as long BOM is "published only"), and then reuse BOM in same way as any external BOM would be reused: by importing within reactor. But, importing within reactor causes "build peculiarities" usually unexpected to users. Hence, we think that _generating BOMs_ simply prevents the two issues, as reactor dependendencies should be managed using inheritance, as it was always the case with Maven. Appearance of BOMs simply caused this "boost of creativity", to reuse them within reactor, but also publish them to downstream users, and it is wrong. Hence, Maven 4 shows an "example", and generates it's own BOMs. Related https://issues.apache.org/jira/browse/MNG-8012 and https://issues.apache.org/jira/browse/MNG-8009
In short: only external BOMs should be imported to reactor.
As per "what is a BOM", there is a split among us as can be seen in this old PR: https://github.com/apache/maven/pull/689
In short, for some, "[BOM represents only the set of modules of a multimodule](https://github.com/apache/maven/pull/689#issuecomment-1061640064)" (only the reactor, so to say) while for others (@gnodet and me included) "BOM is bill of materials", so full stack (if I do an extension for Maven version X, I want same version of resolver, logging, Sisu etc as well... Similarly, look at all our plugins: after version property defining Maven version that plugins builds against, property is usually followed by a section with bunch of "keep in lockstep with Maven" version properties for logging, resolver, etc). Hence, the "skinny" (first definition) vs "fat" (second definition). In fact, Maven4 generates both now, so pleases both parties.
Of course, Maven 4 build generated BOMs can be used only in Maven 4 builds, as only Maven 4 allows importing BOMs with classifiers... So for Maven3, this is still an issue.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "cstamas (via GitHub)" <gi...@apache.org>.
cstamas commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894113312
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's new in Maven 4?
+
+Maven is over 20 years old and is one of the most used build-tool in the Java world.
+Since all the years one important rule was the highest backward-compatibility as possible, especially with
+its [POM-schema with Model version 4.0.0][2], used for the build itself, but also by consumers.
+This made Maven more than a tool, but a whole ecosystem with a lot of things depended on the POM, esp. the Maven Central
+repository, other build tools and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare to changes which are impossible nowadays, like a complete new build schema.
+
+Another pain point of Maven 3 is a code base with a lot of deprecated, convoluted, non performant and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebases contains old Java code that can be optimized nowadays, but also old
+dependencies and bad API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM-Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction the Model version 4.0.0 is used not only for the build, but also by consumers of the
+artifact.
+But several contents of the POM are only necessary for the build while others like the dependencies are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As names suggest the "Build-POM" will contain all information needed for to build the artifact, e.g. used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep those which are really needed to use the artifact, e.g. dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4 a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others got marked as deprecated.
+To not break the ecosystem this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as like every software update - it's suggested to update them to 4.1.0, e.g. to avoid problems when deprecated
+things get removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 till today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files the wording "Maven project" is used.
+However, project containing multiple parts, e.g. an API and a client, each of those parts was called "module" and listed
+in the `<modules>` section of the POM, leading to the terms of "multi-module project".
+This wording introduced some inconsistency, especially as projects with any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9 the term "module" raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>`analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency managing BOMs.
+While the new type is only available with model Version 4.1.0 the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2004][5].
+
+**Note**: With Maven 4 it's also possible to exclude dependencies which are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven4 importing BOMs with classifier is now possible.
+Therefore, Maven team suggests that projects BOMs be generated as classified artifacts (see Maven build "skinny" vs "
Review Comment:
https://github.com/apache/maven/blob/575ad3719c79b061c78d531ec9d29793f159c2ec/apache-maven/pom.xml#L235
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "mthmulders (via GitHub)" <gi...@apache.org>.
mthmulders commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1916069147
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
Review Comment:
When reviewing, I appreciated these initial paragraphs. They gave me the context and an idea of what to expect going forward. From my side, +1 for keeping them.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "elharo (via GitHub)" <gi...@apache.org>.
elharo commented on PR #598:
URL: https://github.com/apache/maven-site/pull/598#issuecomment-2608305264
For this PR it should call out that the namespace used to be http://maven.apache.org/POM/4.0.0 and is now http://maven.apache.org/POM/4.1.0
For the general Issue I filed a bug in Jira. Versions in namespace URIs is an antipattern, though a common one.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "nkonev (via GitHub)" <gi...@apache.org>.
nkonev commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1926085329
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,477 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is the most widely used build tool in the Java world.
+Throughout the years, Maven has maintained backward compatibility, especially of its [POM file][2] with Model version
+4.0.0.
+
+The POM file fulfills two needs.
+First, the POM holds all the information and configuration, which are needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, for example dependencies, which are needed by projects which depend on the
+artifact.
+These dependent projects are called the "consumers".
+
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+Thus, any change in the POM's schema forces each participant of the ecosystem to either adopt the change or drop
+support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+In order for Maven to evolve, it's necessary to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## Required Java version
+
+Maven 4 requires Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 is only needed to **run Maven**!
+You can still compile against older Java versions using the same [compiler plugin configuration][6] as before.
+If you need to compile against or use another JDK, see the [Guide to Using Toolchains][7] (or the
+article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten Mulders).
+
+## POM Changes
+
+### Consumer POM
+
+Maven 4 generates a stripped down consumer POM that removes build information not needed by consumers, and deploys this
+to the remote repository.
+It does not deploy the `pom.xml` used to build the project.
+
+### Model version 4.1.0
+
+Maven 4 updates the POM version to 4.1.0.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the build POM, while the consumer POM will still use
+version 4.0.0.
+Maven generates the consumer POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 if you don't need to use the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project built with Maven.
+The [top level directory][32] of a Maven project contains at least the source folder `src` and the project's POM file
+`pom.xml`.
+A Maven project may have other Maven projects within subdirectories, each with its own `pom.xml` file.
+Each project within a subdirectory is called a "subproject".
+
+Example: Project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects unless they are linked from the root POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+Projects which have at least one subproject are called "multi-module projects", while those which do not have any
+subprojects are called "single module projects".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated `bom` packaging type to provide a [Bill of Materials BOM][4].
+This now differentiates between parent POMs and dependency-managing BOMs.
+The new type is only available as a build POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible consumer POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build.
+In other words: you should only import external BOMs.
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing build POM and consumer POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "consumer POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, for example plugin configuration!
+* Some of the build-related content which is (as of now) still available in the consumer POM might be available only in
+ the build POM in the future.
+
+| Content | Build POM | Consumer POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a consumer POM based on version 4.1.0, for example
+when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, for example a `maven.config` or
+`jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the build POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, for example when you want to define the path to a `checkstyle-suppressions.xml`
+file for the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+current working directory.
+The `rootDirectory` can only contain a value when either a `.mvn` directory is defined or the `root` attribute is set to
+true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4 those properties were removed or marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 consumer POM is set in stone, the build POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, like `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration.
+
+Example
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, for example `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects can cause confusion in Maven 3.
+When the build of subproject B, which requires subproject A, is failing for whatever reason, Maven 3 is telling
+the user to fix the error and then resume the build with `--resume-from :<nameOfTheFailingSubproject>`.
+But doing this instantly fails the build again, because the required subproject A couldn't be found (as it was not
+rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
Review Comment:
I think we need to write explicitly somewhere
that for the building a subproject we don't need to `install` the root project.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "gnodet (via GitHub)" <gi...@apache.org>.
gnodet commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1922851663
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,468 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is the most widely used build tool in the Java world.
+Throughout the years, Maven has maintained backward compatibility, especially of its [POM file][2] with Model version
+4.0.0.
+
+The POM file fulfills two needs.
+First, the POM holds all the information and configuration, which are needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, for example dependencies, which are needed by projects which depend on the
+artifact.
+These dependent projects are called the "consumers".
+
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+Thus, any change in the POM's schema forces each participant of the ecosystem to either adopt the change or drop
+support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+In order for Maven to evolve, it's necessary to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## Required Java version
+
+Maven 4 requires Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 is only needed to **run Maven**!
+You can still compile against older Java versions using the same [compiler plugin configuration][6] as before.
+If you need to compile against or use another JDK, see the [Guide to Using Toolchains][7] (or the
+article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten Mulders).
+
+## POM Changes
+
+### Consumer POM
+
+Maven 4 generates a stripped down consumer POM that removes build information not needed by consumers, and deploys this
+to the remote repository.
+It does not deploy the `pom.xml` used to build the project.
+
+### Model version 4.1.0
+
+Maven 4 updates the POM version to 4.1.0.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the build POM, while the consumer POM will still use
+version 4.0.0.
+Maven generates the consumer POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 if you don't need to use the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project built with Maven.
+The [top level directory][32] of a Maven project contains at least the source folder `src` and the project's POM file
+`pom.xml`.
+A Maven project may have other Maven projects within subdirectories, each with its own `pom.xml` file.
+Each project within a subdirectory is called a "subproject".
+
+Example: Project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects unless they are linked from the root POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+Projects which have at least one subproject are called "multi-module projects", while those which do not have any
+subprojects are called "single module projects".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated `bom` packaging type to provide a [Bill of Materials BOM][4].
+This now differentiates between parent POMs and dependency-managing BOMs.
+The new type is only available as a build POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible consumer POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build.
+In other words: you should only import external BOMs.
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing build POM and consumer POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "consumer POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, for example plugin configuration!
+* Some of the build-related content which is (as of now) still available in the consumer POM might be available only in
+ the build POM in the future.
+
+| Content | Build POM | Consumer POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a consumer POM based on version 4.1.0, for example
+when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, for example a `maven.config` or
+`jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the build POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, for example when you want to define the path to a `checkstyle-suppressions.xml`
+file for the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+current working directory.
+The `rootDirectory` can only contain a value when either a `.mvn` directory is defined or the `root` attribute is set to
+true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4 those properties were removed or marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 consumer POM is set in stone, the build POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, like `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration.
+
+Example
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, for example `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects can cause confusion in Maven 3.
+When the build of subproject B, which requires subproject A, is failing for whatever reason, Maven 3 is telling
+the user to fix the error and then resume the build with `--resume-from :<nameOfTheFailingSubproject>`.
+But doing this instantly fails the build again, because the required subproject A couldn't be found (as it was not
+rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (for example Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where successfully
+built subprojects were deployed to the (local or remote) repository, but failed subprojects were not.
+This was finally changed in Maven 4 to what most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+in Maven 3, for example using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, always define fixed versions of all the plugins you use.
+By doing this, you are in control of your build.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM.
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which breaks the build when the severity of at least one log
+message matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, for example, `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break.
+Instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+In Maven 3 the lifecycle is an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more consistent execution of dependent phases.
+For example, the `compile` phase must execute after `compile-only` project dependencies have reached the `ready` phase.
+Maven 4 also allows to skip phases (in comparison to the old graph).
+For example, it's possible to `deploy` an artifact without `install`ing it to the user repository.
+
Review Comment:
consistent -> fine grained
The problem is not so much about consistency, rather than expressing dependencies closer to the reality.
For compatibility, the behavior is not really changed by default compared to Maven 3. In order to actually leverage the new tree-based lifecycle, the user has to enable the `concurrent` builder using `-b concurrent`. Running with the concurrent builder will allow finer grained dependency instead of the usual Maven 3 per-project dependency. With the usual builders and run `mvn verify`, a project will run up to the verify phase, before a dependent project can start being built, whereas the concurrent builder will allow a dependant project to be built as soon as the dependencies are at the `ready` phase. Same for `install` vs `deploy`, this is only possible when using the concurrent builder (for compatibility).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "gnodet (via GitHub)" <gi...@apache.org>.
gnodet commented on PR #598:
URL: https://github.com/apache/maven-site/pull/598#issuecomment-2608053018
> This doesn't say that the namespace is changing from http://maven.apache.org/POM/4.0.0 to http://maven.apache.org/POM/4.1.0. IMHO it shouldn't be changing and I'm hopeful this change can be reverted. Mixing versions into namespace URIs is a known XML antipattern. But if it's in play it is a huge change that should be called out here.
What are you referring to exactly ?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "elharo (via GitHub)" <gi...@apache.org>.
elharo commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1932092176
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,477 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is the most widely used build tool in the Java world.
+Throughout the years, Maven has maintained backward compatibility, especially of its [POM file][2] with Model version
+4.0.0.
+
+The POM file fulfills two needs.
+First, the POM holds all the information and configuration, which are needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, for example dependencies, which are needed by projects which depend on the
+artifact.
+These dependent projects are called the "consumers".
+
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+Thus, any change in the POM's schema forces each participant of the ecosystem to either adopt the change or drop
+support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+In order for Maven to evolve, it's necessary to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## Required Java version
+
+Maven 4 requires Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 is only needed to **run Maven**!
+You can still compile against older Java versions using the same [compiler plugin configuration][6] as before.
+If you need to compile against or use another JDK, see the [Guide to Using Toolchains][7] (or the
+article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten Mulders).
+
+## POM Changes
+
+### Consumer POM
+
+Maven 4 generates a stripped down consumer POM that removes build information not needed by consumers, and deploys this
+to the remote repository.
+It does not deploy the `pom.xml` used to build the project.
+
+### Model version 4.1.0
+
+Maven 4 updates the POM version to 4.1.0.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the build POM, while the consumer POM will still use
+version 4.0.0.
+Maven generates the consumer POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 if you don't need to use the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project built with Maven.
+The [top level directory][32] of a Maven project contains at least the source folder `src` and the project's POM file
+`pom.xml`.
+A Maven project may have other Maven projects within subdirectories, each with its own `pom.xml` file.
+Each project within a subdirectory is called a "subproject".
+
+Example: Project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects unless they are linked from the root POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+Projects which have at least one subproject are called "multi-module projects", while those which do not have any
+subprojects are called "single module projects".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated `bom` packaging type to provide a [Bill of Materials BOM][4].
+This now differentiates between parent POMs and dependency-managing BOMs.
+The new type is only available as a build POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible consumer POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build.
+In other words: you should only import external BOMs.
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing build POM and consumer POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "consumer POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, for example plugin configuration!
+* Some of the build-related content which is (as of now) still available in the consumer POM might be available only in
+ the build POM in the future.
+
+| Content | Build POM | Consumer POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a consumer POM based on version 4.1.0, for example
+when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, for example a `maven.config` or
+`jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the build POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, for example when you want to define the path to a `checkstyle-suppressions.xml`
+file for the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+current working directory.
+The `rootDirectory` can only contain a value when either a `.mvn` directory is defined or the `root` attribute is set to
+true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4 those properties were removed or marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 consumer POM is set in stone, the build POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, like `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration.
+
+Example
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, for example `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects can cause confusion in Maven 3.
+When the build of subproject B, which requires subproject A, is failing for whatever reason, Maven 3 is telling
+the user to fix the error and then resume the build with `--resume-from :<nameOfTheFailingSubproject>`.
+But doing this instantly fails the build again, because the required subproject A couldn't be found (as it was not
+rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
Review Comment:
agreed, this document is just for a quick summary of what's new. It's not for documenting the new or existing features in detail.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1898872695
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, and duplicate code
+which costs the developers who maintain Maven a lot of time.
+This means that the Maven codebase contains not only old Java code but also old dependencies and poor API design of its
+own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only by the build but also by consumers of the
+artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
Review Comment:
Rephrased
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1917002719
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,496 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+On the one side, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact was created, these build information are not relevant anymore.
+On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use
+the artifact, e.g. dependencies.
Review Comment:
Oh it's twice. Shall I delete both or only the second on line 35 where your comment it?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "elharo (via GitHub)" <gi...@apache.org>.
elharo commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1921067211
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
Review Comment:
one of the most used build tools --> the most widely used build tool
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
Review Comment:
configuration, which are only needed
-->
which are needed
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
Review Comment:
root directory
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
Review Comment:
remove parentheses
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
Review Comment:
The language here is confusing. I think the root folder is where the pom.xml resides. This is something else. One or the other must be renamed.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+directory is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those properties were removed
+or at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone, the Build-POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, e.g., `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject depended on one of the
+others and its own build failed for whatever reason.
Review Comment:
antecedent of its is unclear; rewrite
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
Review Comment:
In Maven 3 both the build and consumers use the same pom file with model version 4.0.0.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
Review Comment:
This results in the situation that ---> Thus
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+directory is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those properties were removed
+or at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone, the Build-POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, e.g., `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject depended on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to fix the error and then resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before.
+If this does not fit your requirements because you need to compile against or use another JDK, see
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
Review Comment:
delete already
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
Review Comment:
delete elementary
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
Review Comment:
"But Maven should be able to advance.
For this, one important thing that's needed is to"
-->
In order for Maven to evolve, it's necessary to"
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
Review Comment:
which want to use the artifact.
-->
which depend on the artifact.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
Review Comment:
built
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
Review Comment:
one important rule has been maintaining the highest backward compatibility possible
-->
Maven has maintained backward compatibility
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
Review Comment:
the Maven --> Maven
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+directory is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those properties were removed
+or at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone, the Build-POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, e.g., `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject depended on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to fix the error and then resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before.
+If this does not fit your requirements because you need to compile against or use another JDK, see
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, always define fixed versions of all the plugins you use.
+By doing this, you are in control of your build.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM.
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which breaks the build when the severity of at least one log
+message matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, e.g., `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break; instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3, the lifecycle was an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more consistent execution of dependent phases, e.g., `compile` must execute after `compile-only` project
+dependencies have reached the `ready` phase, and also allows "skipping" phases (in comparison to the old graph), e.g.,
+`deploy` an artifact without `install`ing it to the user repository.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before` and `after` phase, allowing plugins to bind themselves to those by adding their
Review Comment:
and an
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
Review Comment:
Maybe build POM and consumer POM shouldn't be hyphenated
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
Review Comment:
source folder `src`
POM file `pom.xml`
delete "test source folder". Not all projects have it
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
Review Comment:
delete this sentence. Wording was not inconsistent. It's being changed now
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
Review Comment:
as long as you don't want to make use of the new features
-->
if you don't need to use the new features
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
Review Comment:
as long as they are not linked as such
-->
unless they are linked from the root POM file
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+directory is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those properties were removed
+or at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone, the Build-POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, e.g., `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject depended on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to fix the error and then resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before.
+If this does not fit your requirements because you need to compile against or use another JDK, see
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, always define fixed versions of all the plugins you use.
+By doing this, you are in control of your build.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM.
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which breaks the build when the severity of at least one log
+message matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, e.g., `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break; instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3, the lifecycle was an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more consistent execution of dependent phases, e.g., `compile` must execute after `compile-only` project
+dependencies have reached the `ready` phase, and also allows "skipping" phases (in comparison to the old graph), e.g.,
+`deploy` an artifact without `install`ing it to the user repository.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before` and `after` phase, allowing plugins to bind themselves to those by adding their
+prefixes to the name of the main phase.
+For example, if you want to set up test data before running your integration tests, you could execute tasks during the
+`before-integration-test` phase.
+
+If this is not enough, perhaps because you want to do multiple things inside the same phase, you can order each
+execution inside a phase by using square brackets with an integer at the end of the phase name, e.g.,
+
+```
+before-integration-test[100]
+before-integration-test[200]
+```
+
+**Warning**: The conceptual `pre-*` and `post-*` phases, which were only available for selected phases and had
+inconsistent naming, are deprecated - don't use them!
+This becomes even more important if you were binding a plugin to the `post-*` phase of a lifecycle phase because the
Review Comment:
were --> are
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
Review Comment:
subdirectories --> subdirectory
called a
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+directory is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those properties were removed
+or at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone, the Build-POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, e.g., `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject depended on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to fix the error and then resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before.
+If this does not fit your requirements because you need to compile against or use another JDK, see
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, always define fixed versions of all the plugins you use.
+By doing this, you are in control of your build.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM.
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which breaks the build when the severity of at least one log
+message matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, e.g., `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break; instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3, the lifecycle was an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more consistent execution of dependent phases, e.g., `compile` must execute after `compile-only` project
+dependencies have reached the `ready` phase, and also allows "skipping" phases (in comparison to the old graph), e.g.,
+`deploy` an artifact without `install`ing it to the user repository.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before` and `after` phase, allowing plugins to bind themselves to those by adding their
+prefixes to the name of the main phase.
+For example, if you want to set up test data before running your integration tests, you could execute tasks during the
+`before-integration-test` phase.
+
+If this is not enough, perhaps because you want to do multiple things inside the same phase, you can order each
+execution inside a phase by using square brackets with an integer at the end of the phase name, e.g.,
+
+```
+before-integration-test[100]
+before-integration-test[200]
+```
+
+**Warning**: The conceptual `pre-*` and `post-*` phases, which were only available for selected phases and had
+inconsistent naming, are deprecated - don't use them!
Review Comment:
- don't
. Don't
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
Review Comment:
A Maven project may have other Maven projects within subdirectories.
-->
A Maven project may have other Maven projects within subdirectories, each with its own pom.xml file.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
Review Comment:
are often called "multi-module project",
-->
are called "multi-module projects",
have any --> have any subprojects
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
Review Comment:
(in other words: you should import only external BOMs).
-->
. In other words: you should only import external BOMs.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
Review Comment:
Maven 4 introduces a dedicated `bom` packaging type to provide a [Bill of Materials BOM][4]. This now differentiates between parent POMs and dependency-managing BOMs.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
Review Comment:
are called "single module projects"
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
Review Comment:
This feels like a bug we should fix before releasing 4.0 (not in this PR)
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+directory is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM
Review Comment:
delete still
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
Review Comment:
sounds like the current working directory, and we should probably just say that
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+directory is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
Review Comment:
OK, so we now have top, root, and base directories
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+directory is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
Review Comment:
Maybe one is a root directory and one is a top directory? This needs to be majorly clarified before we release 4.0. It might require code changes.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+directory is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those properties were removed
+or at least marked as deprecated.
Review Comment:
delete "at least"
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+directory is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those properties were removed
Review Comment:
will they work or not? Be definite about this.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+directory is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those properties were removed
+or at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone, the Build-POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, e.g., `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject depended on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to fix the error and then resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
Review Comment:
some (successfully
built) --> successfully
built
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+directory is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those properties were removed
+or at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone, the Build-POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, e.g., `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject depended on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to fix the error and then resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
Review Comment:
the way --> what
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+directory is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those properties were removed
+or at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone, the Build-POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, e.g., `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject depended on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to fix the error and then resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
Review Comment:
will still be able to --> can still
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+directory is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those properties were removed
+or at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone, the Build-POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, e.g., `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject depended on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to fix the error and then resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
Review Comment:
will only be --> is only
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+directory is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those properties were removed
+or at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone, the Build-POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, e.g., `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject depended on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to fix the error and then resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
Review Comment:
will be --> is
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+directory is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those properties were removed
+or at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone, the Build-POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, e.g., `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject depended on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to fix the error and then resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before.
+If this does not fit your requirements because you need to compile against or use another JDK, see
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, always define fixed versions of all the plugins you use.
+By doing this, you are in control of your build.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM.
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which breaks the build when the severity of at least one log
+message matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, e.g., `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break; instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3, the lifecycle was an ordered list containing all phases.
Review Comment:
Up to --> In Maven 3 the lifecycle is
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+directory is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those properties were removed
+or at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone, the Build-POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, e.g., `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject depended on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to fix the error and then resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
Review Comment:
delete obviously
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+directory is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those properties were removed
+or at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone, the Build-POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, e.g., `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject depended on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to fix the error and then resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before.
+If this does not fit your requirements because you need to compile against or use another JDK, see
Review Comment:
delete "this does not fit your requirements because"
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+directory is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those properties were removed
+or at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone, the Build-POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, e.g., `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject depended on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to fix the error and then resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before.
+If this does not fit your requirements because you need to compile against or use another JDK, see
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, always define fixed versions of all the plugins you use.
+By doing this, you are in control of your build.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM.
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which breaks the build when the severity of at least one log
+message matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, e.g., `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break; instead, an information message will be printed twice (at the start and end).
Review Comment:
break; instead,
-->
break. Instead,
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+directory is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those properties were removed
+or at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone, the Build-POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, e.g., `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject depended on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to fix the error and then resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before.
+If this does not fit your requirements because you need to compile against or use another JDK, see
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, always define fixed versions of all the plugins you use.
+By doing this, you are in control of your build.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM.
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which breaks the build when the severity of at least one log
+message matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, e.g., `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break; instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3, the lifecycle was an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more consistent execution of dependent phases, e.g., `compile` must execute after `compile-only` project
+dependencies have reached the `ready` phase, and also allows "skipping" phases (in comparison to the old graph), e.g.,
+`deploy` an artifact without `install`ing it to the user repository.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before` and `after` phase, allowing plugins to bind themselves to those by adding their
+prefixes to the name of the main phase.
Review Comment:
antecedent of their is unclear
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+directory is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those properties were removed
+or at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone, the Build-POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, e.g., `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject depended on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to fix the error and then resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before.
+If this does not fit your requirements because you need to compile against or use another JDK, see
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, always define fixed versions of all the plugins you use.
+By doing this, you are in control of your build.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM.
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which breaks the build when the severity of at least one log
+message matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, e.g., `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break; instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3, the lifecycle was an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more consistent execution of dependent phases, e.g., `compile` must execute after `compile-only` project
+dependencies have reached the `ready` phase, and also allows "skipping" phases (in comparison to the old graph), e.g.,
+`deploy` an artifact without `install`ing it to the user repository.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before` and `after` phase, allowing plugins to bind themselves to those by adding their
+prefixes to the name of the main phase.
+For example, if you want to set up test data before running your integration tests, you could execute tasks during the
+`before-integration-test` phase.
+
+If this is not enough, perhaps because you want to do multiple things inside the same phase, you can order each
+execution inside a phase by using square brackets with an integer at the end of the phase name, e.g.,
Review Comment:
name, For example,
(In general avoid Latin: i.e., e.g., n.b., etc.)
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+directory is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those properties were removed
+or at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone, the Build-POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, e.g., `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject depended on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to fix the error and then resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before.
+If this does not fit your requirements because you need to compile against or use another JDK, see
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, always define fixed versions of all the plugins you use.
+By doing this, you are in control of your build.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM.
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which breaks the build when the severity of at least one log
+message matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, e.g., `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break; instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3, the lifecycle was an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more consistent execution of dependent phases, e.g., `compile` must execute after `compile-only` project
+dependencies have reached the `ready` phase, and also allows "skipping" phases (in comparison to the old graph), e.g.,
Review Comment:
run-on sentence
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+directory is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those properties were removed
+or at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone, the Build-POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, e.g., `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject depended on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to fix the error and then resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before.
+If this does not fit your requirements because you need to compile against or use another JDK, see
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, always define fixed versions of all the plugins you use.
+By doing this, you are in control of your build.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM.
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which breaks the build when the severity of at least one log
+message matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, e.g., `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break; instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3, the lifecycle was an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more consistent execution of dependent phases, e.g., `compile` must execute after `compile-only` project
+dependencies have reached the `ready` phase, and also allows "skipping" phases (in comparison to the old graph), e.g.,
+`deploy` an artifact without `install`ing it to the user repository.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before` and `after` phase, allowing plugins to bind themselves to those by adding their
+prefixes to the name of the main phase.
+For example, if you want to set up test data before running your integration tests, you could execute tasks during the
+`before-integration-test` phase.
+
+If this is not enough, perhaps because you want to do multiple things inside the same phase, you can order each
+execution inside a phase by using square brackets with an integer at the end of the phase name, e.g.,
+
+```
+before-integration-test[100]
+before-integration-test[200]
+```
+
+**Warning**: The conceptual `pre-*` and `post-*` phases, which were only available for selected phases and had
+inconsistent naming, are deprecated - don't use them!
+This becomes even more important if you were binding a plugin to the `post-*` phase of a lifecycle phase because the
+`pre-*` phase of the phase you really wanted to bind to did not exist, e.g., binding to `process-resources` phase
+because there was no `pre-compile` phase.
+
+## Maven plugins, security and tools
Review Comment:
security,
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
Review Comment:
The whole build consumer POM distinction can be ignored by a lot of users. However their existing build just fails when they try to run with Java 11 like they did with maven 3.9.9.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+directory is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those properties were removed
+or at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone, the Build-POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, e.g., `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject depended on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to fix the error and then resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before.
+If this does not fit your requirements because you need to compile against or use another JDK, see
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, always define fixed versions of all the plugins you use.
+By doing this, you are in control of your build.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM.
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which breaks the build when the severity of at least one log
+message matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, e.g., `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break; instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3, the lifecycle was an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more consistent execution of dependent phases, e.g., `compile` must execute after `compile-only` project
+dependencies have reached the `ready` phase, and also allows "skipping" phases (in comparison to the old graph), e.g.,
+`deploy` an artifact without `install`ing it to the user repository.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before` and `after` phase, allowing plugins to bind themselves to those by adding their
+prefixes to the name of the main phase.
+For example, if you want to set up test data before running your integration tests, you could execute tasks during the
+`before-integration-test` phase.
+
+If this is not enough, perhaps because you want to do multiple things inside the same phase, you can order each
+execution inside a phase by using square brackets with an integer at the end of the phase name, e.g.,
+
+```
+before-integration-test[100]
+before-integration-test[200]
+```
+
+**Warning**: The conceptual `pre-*` and `post-*` phases, which were only available for selected phases and had
+inconsistent naming, are deprecated - don't use them!
+This becomes even more important if you were binding a plugin to the `post-*` phase of a lifecycle phase because the
+`pre-*` phase of the phase you really wanted to bind to did not exist, e.g., binding to `process-resources` phase
Review Comment:
wanted --> want
did -- does
In general, prefer present tense
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "cstamas (via GitHub)" <gi...@apache.org>.
cstamas commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894104074
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's new in Maven 4?
+
+Maven is over 20 years old and is one of the most used build-tool in the Java world.
+Since all the years one important rule was the highest backward-compatibility as possible, especially with
+its [POM-schema with Model version 4.0.0][2], used for the build itself, but also by consumers.
+This made Maven more than a tool, but a whole ecosystem with a lot of things depended on the POM, esp. the Maven Central
+repository, other build tools and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare to changes which are impossible nowadays, like a complete new build schema.
+
+Another pain point of Maven 3 is a code base with a lot of deprecated, convoluted, non performant and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebases contains old Java code that can be optimized nowadays, but also old
+dependencies and bad API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM-Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction the Model version 4.0.0 is used not only for the build, but also by consumers of the
+artifact.
+But several contents of the POM are only necessary for the build while others like the dependencies are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As names suggest the "Build-POM" will contain all information needed for to build the artifact, e.g. used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep those which are really needed to use the artifact, e.g. dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4 a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others got marked as deprecated.
+To not break the ecosystem this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as like every software update - it's suggested to update them to 4.1.0, e.g. to avoid problems when deprecated
+things get removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 till today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files the wording "Maven project" is used.
+However, project containing multiple parts, e.g. an API and a client, each of those parts was called "module" and listed
+in the `<modules>` section of the POM, leading to the terms of "multi-module project".
+This wording introduced some inconsistency, especially as projects with any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9 the term "module" raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>`analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency managing BOMs.
+While the new type is only available with model Version 4.1.0 the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2004][5].
+
+**Note**: With Maven 4 it's also possible to exclude dependencies which are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven4 importing BOMs with classifier is now possible.
+Therefore, Maven team suggests that projects BOMs be generated as classified artifacts (see Maven build "skinny" vs "
Review Comment:
Our stance (@gnodet could chime in when online) is following: BOMs should be _generated_ and not used within reactor (see issues), because users are "tempted" to create BOMs within reactor (is fine, as long BOM is "published only"), and then reuse BOM in same way as any external BOM would be reused: by importing. But, importing causes "build peculiarities" usually unexpected to users. Hence, we think that _generating BOMs_ simply prevents the two issues, as reactor dependendencies should be managed using inheritance, as it was always the case with Maven. Appearance of BOMs simply caused this "boost of creativity", to reuse them within reactor, but also publish them to downstream users, and it is wrong. Hence, Maven 4 shows an "example", and generates it's own BOMs. Related https://issues.apache.org/jira/browse/MNG-8012 and https://issues.apache.org/jira/browse/MNG-8009
As per "what is a BOM", there is a split among us as can be seen in this old PR: https://github.com/apache/maven/pull/689
In short, for some, "[BOM represents only the set of modules of a multimodule](https://github.com/apache/maven/pull/689#issuecomment-1061640064)" (only the reactor, so to say) while for others (@gnodet and me included) "BOM is bill of materials", so full stack (if I do an extension for Maven version X, I want same version of resolver, logging, Sisu etc as well... Similarly, look at all our plugins: after version property defining Maven version that plugins builds against, property is usually followed by a section with bunch of "keep in lockstep with Maven" version properties for logging, resolver, etc). Hence, the "skinny" (first definition) vs "fat" (second definition). In fact, Maven4 generates both now, so pleases both parties.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on PR #598:
URL: https://github.com/apache/maven-site/pull/598#issuecomment-2559661295
Thank you for your feedback @elharo! Integrated all of your text suggestions and left the two questions/doubts for further responses/discussion - I'm open to everything.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "elharo (via GitHub)" <gi...@apache.org>.
elharo commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1895778308
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
Review Comment:
I'm not sure we can expect people reading this document to already know the difference between build and consumers. This should probably be carefully explained right up front.
Also, "consumers" is a strange term here. I might consider dependents instead, but either way it does need to be defined.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
Review Comment:
Consider the audience of this document. This simply is not relevant to someone who simply wants to use Maven to build their code. It's only relevant to the people developing Maven and that's not who this is written for.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicate code
+which costs the volunteers who maintain Maven a lot of time.
+This means that the Maven codebase contains not only old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only by the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements because you need to compile against or use another JDK, please look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was held in March 2024, shortly before Java 22 was
+released. One reason Java 17 was chosen over Java 21 was that it was (at this time) the second-last Java version for
+which many vendors offer long-term support.*
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates and even removals.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only the use of newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, you should always define fixed versions of all the plugins you use!
+By doing this, you are in control of your build - at the cost of being responsible for upgrading the versions yourself.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM!
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which will break the build when at least one log message
+matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, e.g., `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break; instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3, the lifecycle was an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more consistent execution of dependent phases, e.g., `compile` must execute after `compile-only` project
+dependencies have reached the `ready` phase, and also allows "skipping" phases (in comparison to the old graph), e.g.,
+`deploy` an artifact without `install`ing it to the user repository.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before` and `after` phase, allowing plugins to bind themselves to those by adding their
+prefixes to the name of the main phase.
+For example, if you want to set up test data before running your integration tests, you could execute tasks during the
+`before-integration-test` phase.
+
+If this is not enough, perhaps because you want to do multiple things inside the same phase, you can order each
+execution inside a phase by using square brackets with an integer at the end of the phase name, e.g.,
+
+```
+before-integration-test[100]
+before-integration-test[200]
+```
+
+**Warning**: The conceptual `pre-*` and `post-*` phases, which were only available for selected phases and had
+inconsistent naming, are deprecated - don't use them!
+This becomes even more important if you were binding a plugin to the `post-*` phase of a lifecycle phase because the
+`pre-*` phase of the phase you really wanted to bind to did not exist, e.g., binding to `process-resources` phase
+because there was no `pre-compile` phase.
+
+## Maven plugins, security and tools
+
+### Maven plugins
+
+As mentioned above, Maven 4 contains significant code and API updates, resulting in breaking changes for (very) old
+Maven plugins that were not updated to use the recommended APIs.
Review Comment:
were not --> have not been
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1932458087
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,477 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is the most widely used build tool in the Java world.
+Throughout the years, Maven has maintained backward compatibility, especially of its [POM file][2] with Model version
+4.0.0.
+
+The POM file fulfills two needs.
+First, the POM holds all the information and configuration, which are needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, for example dependencies, which are needed by projects which depend on the
+artifact.
+These dependent projects are called the "consumers".
+
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+Thus, any change in the POM's schema forces each participant of the ecosystem to either adopt the change or drop
+support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+In order for Maven to evolve, it's necessary to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## Required Java version
+
+Maven 4 requires Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 is only needed to **run Maven**!
+You can still compile against older Java versions using the same [compiler plugin configuration][6] as before.
+If you need to compile against or use another JDK, see the [Guide to Using Toolchains][7] (or the
+article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten Mulders).
+
+## POM Changes
+
+### Consumer POM
+
+Maven 4 generates a stripped down consumer POM that removes build information not needed by consumers, and deploys this
+to the remote repository.
+It does not deploy the `pom.xml` used to build the project.
+
+### Model version 4.1.0
+
+Maven 4 updates the POM version to 4.1.0 which defines the namespace `http://maven.apache.org/POM/4.1.0`.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the build POM, while the consumer POM will still use
+version 4.0.0.
+Maven generates the consumer POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 if you don't need to use the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project built with Maven.
+The [top level directory][32] of a Maven project contains at least the source folder `src` and the project's POM file
+`pom.xml`.
+A Maven project may have other Maven projects within subdirectories, each with its own `pom.xml` file.
+Each project within a subdirectory is called a "subproject".
+
+Example: Project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects unless they are linked from the root POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+Projects which have at least one subproject are called "multi-module projects", while those which do not have any
+subprojects are called "single module projects".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated `bom` packaging type to provide a [Bill of Materials BOM][4].
+This now differentiates between parent POMs and dependency-managing BOMs.
+The new type is only available as a build POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible consumer POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build.
+In other words: you should only import external BOMs.
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing build POM and consumer POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "consumer POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, for example plugin configuration!
+* Some of the build-related content which is (as of now) still available in the consumer POM might be available only in
+ the build POM in the future.
+
+| Content | Build POM | Consumer POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a consumer POM based on version 4.1.0, for example
+when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, for example a `maven.config` or
+`jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the build POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, for example when you want to define the path to a `checkstyle-suppressions.xml`
+file for the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+current working directory.
+The `rootDirectory` can only contain a value when either a `.mvn` directory is defined or the `root` attribute is set to
+true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4 those properties were removed or marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 consumer POM is set in stone, the build POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, like `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration.
+
+Example
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, for example `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects can cause confusion in Maven 3.
+When the build of subproject B, which requires subproject A, is failing for whatever reason, Maven 3 is telling
+the user to fix the error and then resume the build with `--resume-from :<nameOfTheFailingSubproject>`.
+But doing this instantly fails the build again, because the required subproject A couldn't be found (as it was not
+rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (for example Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where successfully
+built subprojects were deployed to the (local or remote) repository, but failed subprojects were not.
+This was finally changed in Maven 4 to what most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+in Maven 3, for example using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, always define fixed versions of all the plugins you use.
+By doing this, you are in control of your build.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM.
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which breaks the build when the severity of at least one log
+message matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, for example, `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break.
+Instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+In Maven 3 the lifecycle is an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more fine-grained execution of dependent phases.
+For example, the `compile` phase must execute after `compile-only` project dependencies have reached the `ready` phase.
+Maven 4 also allows to skip phases (in comparison to the old graph).
+For example, it's possible to `deploy` an artifact without `install`ing it to the user repository.
+
+For compatibility, the execution behavior is not really changed by default compared to Maven 3.
+In order to actually leverage the new tree-based lifecycle, the user has to enable the concurrent builder using
+`-b concurrent`.
+Running with the concurrent builder will allow finer grained dependency instead of the usual Maven 3 per-project
+dependency.
+With the usual builders and run `mvn verify`, a project will run up to the verify phase, before a dependent project can
+start being built, whereas the concurrent builder will allow a dependant project to be built as soon as the dependencies
+are at the `ready` phase.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before:` and an `after:` phase, allowing plugins to bind themselves to those.
+For example, if you want to set up test data before running your integration tests, you could execute tasks during the
+`before:integration-test` phase.
+
+If this is not enough, perhaps because you want to do multiple things inside the same phase, you can order each
+execution inside a phase by using square brackets with an integer at the end of the phase name.
+
+Example
+
+```
+before:integration-test[100]
+before:integration-test[200]
+```
+
+**Warning**: The conceptual `pre-*` and `post-*` phases, which were only available for selected phases and had
+inconsistent naming, are deprecated.
+Don't use them!
+This becomes even more important if you are binding a plugin to the `post-*` phase of a lifecycle phase because the
+`pre-*` phase of the phase you really want to bind to does not exist, for example, binding to `process-resources` phase
+because there was no `pre-compile` phase.
+
+## Maven plugins, security, and tools
+
+### Maven plugins
+
+As mentioned above, Maven 4 contains significant code and API updates, resulting in breaking changes for (very) old
+Maven plugins that have not been updated to use the recommended APIs.
+Major changes regarding plugins include a proper immutable plugin model together with a revised plugin API.
+The updated API provides hints as preparation for Maven 4.
+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.
+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.
+
+**Advice**: If you are maintaining a Maven plugin, you should test it with Maven 3.9.x.
+Pay close attention to upcoming warnings and update the plugin accordingly.
+
+### Improved encryption
+
+Security is important, and storing unencrypted passwords is bad practice.
+Maven 3's password encryption had several serious issues and could more accurately be called "password obfuscation".
+Maven 4 instead has a completely redone encryption system, based on Maven Encryption (`mvnenc`) - a standalone CLI tool.
Review Comment:
> But
>
> > based on Maven Encryption (`mvnenc`) - a standalone CLI tool.
>
> feels wrong to me. I would rather remove the sentence then altogether.
The phrasing is based on @cstamas blog about it:
> Maven4 password encryption is handled by the new CLI tool: mvnenc.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894402330
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,459 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially with
+its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven Central
+repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module" and listed
+in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a fully Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use of
+the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for the
+checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should be
+able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config` file
+or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements because you need to compile against or use another JDK, please look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was held in March 2024, shortly before Java 22 was
+released. One reason Java 17 was chosen over Java 21 was that it was (at this time) the second-last Java version for which many
+vendors offer long-term support.*
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates and even removals.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only the use of newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even if
+you didn't purposely change anything.
+To avoid this situation, you should always define fixed versions of all the plugins you use!
+By doing this, you are in control of your build - at the cost of being responsible for upgrading the versions yourself.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM!
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which will break the build when at least one log message
+matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, e.g., `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break; instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3, the lifecycle was a mathematical graph.
Review Comment:
Rephrased it.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "cstamas (via GitHub)" <gi...@apache.org>.
cstamas commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894165644
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's new in Maven 4?
+
+Maven is over 20 years old and is one of the most used build-tool in the Java world.
+Since all the years one important rule was the highest backward-compatibility as possible, especially with
+its [POM-schema with Model version 4.0.0][2], used for the build itself, but also by consumers.
+This made Maven more than a tool, but a whole ecosystem with a lot of things depended on the POM, esp. the Maven Central
+repository, other build tools and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare to changes which are impossible nowadays, like a complete new build schema.
+
+Another pain point of Maven 3 is a code base with a lot of deprecated, convoluted, non performant and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebases contains old Java code that can be optimized nowadays, but also old
+dependencies and bad API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM-Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction the Model version 4.0.0 is used not only for the build, but also by consumers of the
+artifact.
+But several contents of the POM are only necessary for the build while others like the dependencies are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As names suggest the "Build-POM" will contain all information needed for to build the artifact, e.g. used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep those which are really needed to use the artifact, e.g. dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4 a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others got marked as deprecated.
+To not break the ecosystem this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as like every software update - it's suggested to update them to 4.1.0, e.g. to avoid problems when deprecated
+things get removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 till today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files the wording "Maven project" is used.
+However, project containing multiple parts, e.g. an API and a client, each of those parts was called "module" and listed
+in the `<modules>` section of the POM, leading to the terms of "multi-module project".
+This wording introduced some inconsistency, especially as projects with any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9 the term "module" raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>`analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency managing BOMs.
+While the new type is only available with model Version 4.1.0 the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2004][5].
+
+**Note**: With Maven 4 it's also possible to exclude dependencies which are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven4 importing BOMs with classifier is now possible.
+Therefore, Maven team suggests that projects BOMs be generated as classified artifacts (see Maven build "skinny" vs "
Review Comment:
I'd leave that to @mthmulders but am free to answer to any new upcoming question! (and my grammar is bad as well).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "gnodet (via GitHub)" <gi...@apache.org>.
gnodet commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894469281
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -325,11 +329,11 @@ See [MNG-8286][27] for more information about supported functions.
#### Lifecycle changed from graph to tree
-Up to Maven 3, the lifecycle was a mathematical graph.
+Up to Maven 3 the lifecycle was a literally an ordered list which contains all phases.
Review Comment:
`Up to Maven 3, the lifecycle was literally an ordered list containing all phases.`
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1898712752
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
Review Comment:
> variables or properties?
Good catch! Properties is the correct term, updating.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894093815
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's new in Maven 4?
+
+Maven is over 20 years old and is one of the most used build-tool in the Java world.
+Since all the years one important rule was the highest backward-compatibility as possible, especially with
+its [POM-schema with Model version 4.0.0][2], used for the build itself, but also by consumers.
+This made Maven more than a tool, but a whole ecosystem with a lot of things depended on the POM, esp. the Maven Central
+repository, other build tools and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare to changes which are impossible nowadays, like a complete new build schema.
+
+Another pain point of Maven 3 is a code base with a lot of deprecated, convoluted, non performant and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebases contains old Java code that can be optimized nowadays, but also old
+dependencies and bad API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM-Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction the Model version 4.0.0 is used not only for the build, but also by consumers of the
+artifact.
+But several contents of the POM are only necessary for the build while others like the dependencies are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As names suggest the "Build-POM" will contain all information needed for to build the artifact, e.g. used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep those which are really needed to use the artifact, e.g. dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4 a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others got marked as deprecated.
+To not break the ecosystem this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as like every software update - it's suggested to update them to 4.1.0, e.g. to avoid problems when deprecated
+things get removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 till today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files the wording "Maven project" is used.
+However, project containing multiple parts, e.g. an API and a client, each of those parts was called "module" and listed
+in the `<modules>` section of the POM, leading to the terms of "multi-module project".
+This wording introduced some inconsistency, especially as projects with any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9 the term "module" raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>`analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency managing BOMs.
+While the new type is only available with model Version 4.1.0 the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2004][5].
+
+**Note**: With Maven 4 it's also possible to exclude dependencies which are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven4 importing BOMs with classifier is now possible.
+Therefore, Maven team suggests that projects BOMs be generated as classified artifacts (see Maven build "skinny" vs "
+fat" BOM).
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison about which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply for artefacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations, where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g. when
+condition based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Everytime a Maven build is executed it has to determine the projects root so identify things like the parent project,
+directory information and so on.
+To "help" Maven finding the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project specific configuration to run Maven, e.g. a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4 there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds the boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false) the directory of this POM file is considered the root directory.
+
+Another pain point in relation of the root directly is that until Maven 4 there was no official variable to make use of
+the root folder in your POM files, e.g. when you want to define the path to a `checkstyle-suppressions.xml` file for the
+checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined it should always have the same value for a given project, whereas the value of the`topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subprojects' own base directory, which was and is still accessibly via the `${basedir}` property for the usage in POM
+files and will always have a value.
+
+**Note:** In the past some people "hacked" workarounds for the`rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4 those "hacks" will most probably not work anymore, because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing central repository, the Build-POM should be
+able to evolve.
+This includes allowing the use of alternate syntaxes, by having Maven 4 providing a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects which uses this features is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected it's no longer required to define the parent versions in each subproject, when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parents and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partly supported usage of CI-friendly variables, e.g. `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4 no additional plugin is needed anymore, but full build-in support is provided.
+You can now use variables as versions in your configuration, e.g.
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by a `maven.config` file
+or as a parameter, e.g. `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent from one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuild too).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due the long-stand
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended to not use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully build subprojects when the overall build failed, and will skip to rebuild
+those if you resume the build.
+With Maven 4 it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g. Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve the daily work with those.
+Thanks to [MNG-6754][14] all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3 each subproject was having a different one.
+This should make it easier to identify the archives which belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in the situation where some (successfully
+build) subprojects where deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users are expecting:
+Only deploy when all subprojects were build successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK, but also comes with a more secure runtime as Java 17 includes more security features earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements, because you need to compile against or using another JDK, please have a look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was hold in March 2024, shortly before Java 22 was
+released.
+One reason Java 17 was chosen over Java 21, because it was (at this time) the second last Java version for which many
+vendors offer long-term-support.*
+
+### Application maintenance
+
+As with every update, especially major ones, large application maintenance happens, containing huge code, API and
+dependency updates and even removals.
+For example the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates contain not only usages of newer Java language features, but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing things that either never should have worked or were only kept for backward-compatibility
+already in Maven 3, e.g. using `${pom.*}` expressions.
+Maven own Super POM was also upgrading, which declares new default versions of Maven's core plugins.
+
+**Note**: Due upgrading the default versions of Maven plugins, your build might behave different that before, even if
+you didn't purposely change anything.
+To avoid this situation you should always define fixed versions of all the plugins you use!
+By doing this you are in control of your build - at the costs of being responsible to upgrade the versions yourself.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM!
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which will break the build when at least one log message
+matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument of a log level severity, e.g. `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so the `?` argument was added to the profile parameter.
+When using this the build won't break, but an information will be printed twice (at the start and the end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more and flexible ways to activate profiles, by providing condition based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3 the lifecycle was mathematical graph.
+This changed with Maven 4 where the lifecycle is defined as a tree of phases.
+This allows a more consistent execution of dependent phases, e.g. `compile` must execute after `compile-only` project
+dependencies have reached the `ready` phase, but also "skipping" phases (in comparison to the old graph), e.g. `deploy`
+an artifact without `install`ing it to the user repository.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before` and `after` phase, allowing plugins to bind themselves to those by adding their
+prefixes to the name of the main phase name.
+For example, if you want to set up test data before running your integration test you could execute stuff during the
+`before-integration-test` phase.
+
+If this is not enough, maybe because you want to do multiple things inside the same phase, you can order each execution
+inside a phase by using square brackets with an Integer at the end of the phase name, e.g.
+
+```
+before-integration-test[100]
+before-integration-test[200]
+```
+
+**Warning**: The conceptional `pre-*` and `post-*` phases, wich were only available to selected phases and homogeneously
+named are deprecated - don't use them (anymore)!
+This becomes even more important when you were binding a plugin to the `post-*` phase of a lifecycle phase, because the
+`pre-*` phase of the phase you really would like to bind to did not exist, e.g. binding to `process-resources` phase,
+because there was no `pre-compile`one.
+
+## Maven plugins, security and tools
+
+### Maven plugins
+
+As written above Maven 4 will contain huge code and API updates, resulting in breaking (very) old Maven plugins, which
+were not updated to the recommended APIs.
+Major changes regarding plugins contain a now proper immutable plugin model together with a changed plugin API.
+The updated API provides hints as a preparation for Maven 4.
+You can enable them passing the following argument to your build: `-Dmaven.plugin.validation=verbose`.
+You should also only rely on the official Maven BOMs when developing plugins.
+If a plugin still relies on long time deprecated and now removed Plexus dependency resolution, it will no longer work
+and needs to be updated to JSR-330 - see [Maven & JSR-330][26] for further information.
+
+**Advice**: If you are maintaining a Maven plugin, you should test it with Maven 3.9.x, have a close look at upcoming
+warnings and update the plugin.
+
+### Improved encryption
+
+Security is important and storing unencrypted passwords is bad.
+Maven 3's password encryption has several serious issues and could rather be call a “password obfuscation”.
+Maven 4 instead got a fully redone encryption, based on Maven Encryption (`mvnenc`) - a standalone CLI tool.
+As for now it provides functionally equivalent operations as Maven 3 (see ["Maven: Password Encryption"][30]), but adds
+improvements like a `decrypt` functionality.
+A brought overview about the problems in Maven 3 and the solution in Maven 4 can be found in the
+article ["Handling sensitive data in Maven"][31] by Maven maintainer Tamás Cservenák.
+
+### Maven Resolver
+
+The [Maven Artifact Resolver][28] is a library for working with artifact repositories and dependency resolution.
+Maven 4 will include the new 2.0 release of this library, which contains more than 150 fixes, upgrades and improvements,
+e.g. a Java native HTTP-Client - thanks to lift of the Java version to JDK 17!
+See the project page for more information!
+
+### Maven Shell
+
+When you run any `mvn` the full chain of booting Java, Maven, load config, do the work, tear down and exit the process
+is done - **every single time**.
+To improve performance and reduce build time you can use the [Maven Daemon][29] (`mvnd`), which manages a pool of N
+resident Maven processes.
+With Maven 4 you can also use the brightly polished "Maven Shell" (`mvnsh`), which will keep exactly one resident Maven
+process as long as the shell is opened.
+Stay tuned for more information about this!
Review Comment:
Removed it. The JIRA-Issue and the PR about the shell do not contain any docs (https://github.com/apache/maven/pull/1982/files). I think @cstamas will write a blog post about it (as 2nd part of https://cstamas.org/blog/2024/12/maven4-ante-portas/ I think?) or add docs later to the official site.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1895723846
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
Review Comment:
What I want to express with that, that the Maven codebase and API got a lot of updates and improvements. It should not be a promise, but a note about this. If we don't do any more updates - the sentence in the notes stays true - the team did put a lot of effort into updates
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "elharo (via GitHub)" <gi...@apache.org>.
elharo commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1927553102
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,477 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is the most widely used build tool in the Java world.
+Throughout the years, Maven has maintained backward compatibility, especially of its [POM file][2] with Model version
+4.0.0.
+
+The POM file fulfills two needs.
+First, the POM holds all the information and configuration, which are needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, for example dependencies, which are needed by projects which depend on the
+artifact.
+These dependent projects are called the "consumers".
+
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+Thus, any change in the POM's schema forces each participant of the ecosystem to either adopt the change or drop
+support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+In order for Maven to evolve, it's necessary to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## Required Java version
+
+Maven 4 requires Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 is only needed to **run Maven**!
+You can still compile against older Java versions using the same [compiler plugin configuration][6] as before.
+If you need to compile against or use another JDK, see the [Guide to Using Toolchains][7] (or the
+article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten Mulders).
+
+## POM Changes
+
+### Consumer POM
+
+Maven 4 generates a stripped down consumer POM that removes build information not needed by consumers, and deploys this
+to the remote repository.
+It does not deploy the `pom.xml` used to build the project.
+
+### Model version 4.1.0
+
+Maven 4 updates the POM version to 4.1.0.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the build POM, while the consumer POM will still use
+version 4.0.0.
+Maven generates the consumer POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 if you don't need to use the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project built with Maven.
+The [top level directory][32] of a Maven project contains at least the source folder `src` and the project's POM file
+`pom.xml`.
+A Maven project may have other Maven projects within subdirectories, each with its own `pom.xml` file.
+Each project within a subdirectory is called a "subproject".
+
+Example: Project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects unless they are linked from the root POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+Projects which have at least one subproject are called "multi-module projects", while those which do not have any
+subprojects are called "single module projects".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated `bom` packaging type to provide a [Bill of Materials BOM][4].
+This now differentiates between parent POMs and dependency-managing BOMs.
+The new type is only available as a build POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible consumer POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build.
+In other words: you should only import external BOMs.
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing build POM and consumer POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "consumer POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, for example plugin configuration!
+* Some of the build-related content which is (as of now) still available in the consumer POM might be available only in
+ the build POM in the future.
+
+| Content | Build POM | Consumer POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a consumer POM based on version 4.1.0, for example
+when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, for example a `maven.config` or
+`jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the build POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, for example when you want to define the path to a `checkstyle-suppressions.xml`
+file for the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+current working directory.
+The `rootDirectory` can only contain a value when either a `.mvn` directory is defined or the `root` attribute is set to
+true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4 those properties were removed or marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 consumer POM is set in stone, the build POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, like `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration.
+
+Example
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, for example `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects can cause confusion in Maven 3.
+When the build of subproject B, which requires subproject A, is failing for whatever reason, Maven 3 is telling
+the user to fix the error and then resume the build with `--resume-from :<nameOfTheFailingSubproject>`.
+But doing this instantly fails the build again, because the required subproject A couldn't be found (as it was not
+rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (for example Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where successfully
+built subprojects were deployed to the (local or remote) repository, but failed subprojects were not.
+This was finally changed in Maven 4 to what most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+in Maven 3, for example using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, always define fixed versions of all the plugins you use.
+By doing this, you are in control of your build.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM.
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which breaks the build when the severity of at least one log
+message matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, for example, `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break.
+Instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+In Maven 3 the lifecycle is an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more fine-grained execution of dependent phases.
+For example, the `compile` phase must execute after `compile-only` project dependencies have reached the `ready` phase.
+Maven 4 also allows to skip phases (in comparison to the old graph).
+For example, it's possible to `deploy` an artifact without `install`ing it to the user repository.
+
+For compatibility, the execution behavior is not really changed by default compared to Maven 3.
+In order to actually leverage the new tree-based lifecycle, the user has to enable the concurrent builder using
+`-b concurrent`.
+Running with the concurrent builder will allow finer grained dependency instead of the usual Maven 3 per-project
+dependency.
+With the usual builders and run `mvn verify`, a project will run up to the verify phase, before a dependent project can
+start being built, whereas the concurrent builder will allow a dependant project to be built as soon as the dependencies
+are at the `ready` phase.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before:` and an `after:` phase, allowing plugins to bind themselves to those.
+For example, if you want to set up test data before running your integration tests, you could execute tasks during the
+`before:integration-test` phase.
+
+If this is not enough, perhaps because you want to do multiple things inside the same phase, you can order each
+execution inside a phase by using square brackets with an integer at the end of the phase name.
+
+Example
+
+```
+before:integration-test[100]
+before:integration-test[200]
+```
+
+**Warning**: The conceptual `pre-*` and `post-*` phases, which were only available for selected phases and had
+inconsistent naming, are deprecated.
+Don't use them!
+This becomes even more important if you are binding a plugin to the `post-*` phase of a lifecycle phase because the
+`pre-*` phase of the phase you really want to bind to does not exist, for example, binding to `process-resources` phase
+because there was no `pre-compile` phase.
+
+## Maven plugins, security, and tools
+
+### Maven plugins
+
+As mentioned above, Maven 4 contains significant code and API updates, resulting in breaking changes for (very) old
+Maven plugins that have not been updated to use the recommended APIs.
+Major changes regarding plugins include a proper immutable plugin model together with a revised plugin API.
+The updated API provides hints as preparation for Maven 4.
+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.
+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.
+
+**Advice**: If you are maintaining a Maven plugin, you should test it with Maven 3.9.x.
+Pay close attention to upcoming warnings and update the plugin accordingly.
+
+### Improved encryption
+
+Security is important, and storing unencrypted passwords is bad practice.
+Maven 3's password encryption had several serious issues and could more accurately be called "password obfuscation".
+Maven 4 instead has a completely redone encryption system, based on Maven Encryption (`mvnenc`) - a standalone CLI tool.
+As of now, it provides functionally equivalent operations as Maven 3 (see ["Maven: Password Encryption"][30]) but adds
+improvements like a `decrypt` functionality.
+A broad overview of the problems in Maven 3 and the solution in Maven 4 can be found in the
+article ["Handling sensitive data in Maven"][31] by Maven maintainer Tamás Cservenák.
+
+### Maven Resolver
+
+The [Maven Artifact Resolver][28] is a library for working with artifact repositories and dependency resolution.
+Maven 4 includes the new 2.0 release of this library, which contains more than 150 fixes, upgrades, and
+improvements, for example, a Java native HTTP-Client - thanks to raising the Java version requirement to JDK 17!
+Another major difference compared to Maven 3 is that in the new major version, the resolver is hidden behind the new
+Maven API and is no longer used directly by plugins.
Review Comment:
I agree. This is a what's new page. It should not be the only or primary source of documentation for any feature. That belongs elsewhere.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1924010971
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,468 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is the most widely used build tool in the Java world.
+Throughout the years, Maven has maintained backward compatibility, especially of its [POM file][2] with Model version
+4.0.0.
+
+The POM file fulfills two needs.
+First, the POM holds all the information and configuration, which are needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, for example dependencies, which are needed by projects which depend on the
+artifact.
+These dependent projects are called the "consumers".
+
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+Thus, any change in the POM's schema forces each participant of the ecosystem to either adopt the change or drop
+support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+In order for Maven to evolve, it's necessary to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## Required Java version
+
+Maven 4 requires Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 is only needed to **run Maven**!
+You can still compile against older Java versions using the same [compiler plugin configuration][6] as before.
+If you need to compile against or use another JDK, see the [Guide to Using Toolchains][7] (or the
+article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten Mulders).
+
+## POM Changes
+
+### Consumer POM
+
+Maven 4 generates a stripped down consumer POM that removes build information not needed by consumers, and deploys this
+to the remote repository.
+It does not deploy the `pom.xml` used to build the project.
+
+### Model version 4.1.0
+
+Maven 4 updates the POM version to 4.1.0.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the build POM, while the consumer POM will still use
+version 4.0.0.
+Maven generates the consumer POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 if you don't need to use the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project built with Maven.
+The [top level directory][32] of a Maven project contains at least the source folder `src` and the project's POM file
+`pom.xml`.
+A Maven project may have other Maven projects within subdirectories, each with its own `pom.xml` file.
+Each project within a subdirectory is called a "subproject".
+
+Example: Project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects unless they are linked from the root POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+Projects which have at least one subproject are called "multi-module projects", while those which do not have any
+subprojects are called "single module projects".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated `bom` packaging type to provide a [Bill of Materials BOM][4].
+This now differentiates between parent POMs and dependency-managing BOMs.
+The new type is only available as a build POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible consumer POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build.
+In other words: you should only import external BOMs.
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing build POM and consumer POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "consumer POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, for example plugin configuration!
+* Some of the build-related content which is (as of now) still available in the consumer POM might be available only in
+ the build POM in the future.
+
+| Content | Build POM | Consumer POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a consumer POM based on version 4.1.0, for example
+when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, for example a `maven.config` or
+`jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the build POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, for example when you want to define the path to a `checkstyle-suppressions.xml`
+file for the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+current working directory.
+The `rootDirectory` can only contain a value when either a `.mvn` directory is defined or the `root` attribute is set to
+true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4 those properties were removed or marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 consumer POM is set in stone, the build POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, like `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration.
+
+Example
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, for example `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects can cause confusion in Maven 3.
+When the build of subproject B, which requires subproject A, is failing for whatever reason, Maven 3 is telling
+the user to fix the error and then resume the build with `--resume-from :<nameOfTheFailingSubproject>`.
+But doing this instantly fails the build again, because the required subproject A couldn't be found (as it was not
+rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (for example Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where successfully
+built subprojects were deployed to the (local or remote) repository, but failed subprojects were not.
+This was finally changed in Maven 4 to what most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+in Maven 3, for example using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, always define fixed versions of all the plugins you use.
+By doing this, you are in control of your build.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM.
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which breaks the build when the severity of at least one log
+message matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, for example, `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break.
+Instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+In Maven 3 the lifecycle is an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more consistent execution of dependent phases.
+For example, the `compile` phase must execute after `compile-only` project dependencies have reached the `ready` phase.
+Maven 4 also allows to skip phases (in comparison to the old graph).
+For example, it's possible to `deploy` an artifact without `install`ing it to the user repository.
+
Review Comment:
Thank you for the explanation - I added it to the article for a better understanding about this feature.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1917027995
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,496 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+On the one side, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact was created, these build information are not relevant anymore.
+On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use
+the artifact, e.g. dependencies.
+These dependent projects, which "consume" an artifact (and its POM), are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation, that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+So Maven's POM file got cemented, not able to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from those needed by the
+consumers, but without breaking in the ecosystem.
+Maven 4 will prepare for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only by the build but also by consumers of the
Review Comment:
Will think about another wording tomorrow. Need to go to local JUG now.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1941745737
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,476 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
Review Comment:
> that feature has been challenged by https://issues.apache.org/jira/browse/MNG-8537
I'm aware of this issue and as far as I understand the discussion it's also the cause why this PR does not move forward. Maybe I should even close it completely. It's open for about 6 weeks now, some don't want to review it cause if its size and as long as it's open from time and time someone sneaks in to request documentation which should be in the explicit pages but not in a summary (@lbruun I don't mean you by this, your ping about the not necessary `<modelVersion>` is totally fine and I would instantly add it, if MNG-8537 would not exists/be closed).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on PR #598:
URL: https://github.com/apache/maven-site/pull/598#issuecomment-2548978270
Info:
* I put the article quite on high in the menu to make it more visible. When Maven 4 grew up a bit it can be (re-)moved.
* I manually edited the `site.xml` to not apply full code style changes as it's not correctly formatted as of now (see #595)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on PR #598:
URL: https://github.com/apache/maven-site/pull/598#issuecomment-2585288169
* Rebased
* Spotless applied and quote line correctly formatted after this
* License added
Is there anything else I need to change / do?
If anyone is worried, I filed an Apache Individual Contributor License Agreement last year (or even in 2023, can't remember)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "elharo (via GitHub)" <gi...@apache.org>.
elharo commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1895655440
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
Review Comment:
What's the impact? Explain why we want this. It's not self-evidently a good thing.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1896756257
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicate code
+which costs the volunteers who maintain Maven a lot of time.
Review Comment:
Changed
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "cstamas (via GitHub)" <gi...@apache.org>.
cstamas commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894104074
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's new in Maven 4?
+
+Maven is over 20 years old and is one of the most used build-tool in the Java world.
+Since all the years one important rule was the highest backward-compatibility as possible, especially with
+its [POM-schema with Model version 4.0.0][2], used for the build itself, but also by consumers.
+This made Maven more than a tool, but a whole ecosystem with a lot of things depended on the POM, esp. the Maven Central
+repository, other build tools and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare to changes which are impossible nowadays, like a complete new build schema.
+
+Another pain point of Maven 3 is a code base with a lot of deprecated, convoluted, non performant and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebases contains old Java code that can be optimized nowadays, but also old
+dependencies and bad API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM-Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction the Model version 4.0.0 is used not only for the build, but also by consumers of the
+artifact.
+But several contents of the POM are only necessary for the build while others like the dependencies are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As names suggest the "Build-POM" will contain all information needed for to build the artifact, e.g. used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep those which are really needed to use the artifact, e.g. dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4 a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others got marked as deprecated.
+To not break the ecosystem this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as like every software update - it's suggested to update them to 4.1.0, e.g. to avoid problems when deprecated
+things get removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 till today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files the wording "Maven project" is used.
+However, project containing multiple parts, e.g. an API and a client, each of those parts was called "module" and listed
+in the `<modules>` section of the POM, leading to the terms of "multi-module project".
+This wording introduced some inconsistency, especially as projects with any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9 the term "module" raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>`analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency managing BOMs.
+While the new type is only available with model Version 4.1.0 the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2004][5].
+
+**Note**: With Maven 4 it's also possible to exclude dependencies which are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven4 importing BOMs with classifier is now possible.
+Therefore, Maven team suggests that projects BOMs be generated as classified artifacts (see Maven build "skinny" vs "
Review Comment:
Our stance (@gnodet could chime in when online) is following: BOMs should be _generated_ and not used within reactor (see issues), because users are "tempted" to create BOMs within reactor (is fine, as long BOM is "published only"), and then reuse BOM in same way as any external BOM would be reused: by importing within reactor. But, importing within reactor causes "build peculiarities" usually unexpected to users. Hence, we think that _generating BOMs_ simply prevents the two issues, as reactor dependendencies should be managed using inheritance, as it was always the case with Maven. Appearance of BOMs simply caused this "boost of creativity", to reuse them within reactor, but also publish them to downstream users, and it is wrong. Hence, Maven 4 shows an "example", and generates it's own BOMs. Related https://issues.apache.org/jira/browse/MNG-8012 and https://issues.apache.org/jira/browse/MNG-8009
As per "what is a BOM", there is a split among us as can be seen in this old PR: https://github.com/apache/maven/pull/689
In short, for some, "[BOM represents only the set of modules of a multimodule](https://github.com/apache/maven/pull/689#issuecomment-1061640064)" (only the reactor, so to say) while for others (@gnodet and me included) "BOM is bill of materials", so full stack (if I do an extension for Maven version X, I want same version of resolver, logging, Sisu etc as well... Similarly, look at all our plugins: after version property defining Maven version that plugins builds against, property is usually followed by a section with bunch of "keep in lockstep with Maven" version properties for logging, resolver, etc). Hence, the "skinny" (first definition) vs "fat" (second definition). In fact, Maven4 generates both now, so pleases both parties.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "mthmulders (via GitHub)" <gi...@apache.org>.
mthmulders commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894012682
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's new in Maven 4?
+
+Maven is over 20 years old and is one of the most used build-tool in the Java world.
+Since all the years one important rule was the highest backward-compatibility as possible, especially with
+its [POM-schema with Model version 4.0.0][2], used for the build itself, but also by consumers.
+This made Maven more than a tool, but a whole ecosystem with a lot of things depended on the POM, esp. the Maven Central
+repository, other build tools and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare to changes which are impossible nowadays, like a complete new build schema.
+
+Another pain point of Maven 3 is a code base with a lot of deprecated, convoluted, non performant and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebases contains old Java code that can be optimized nowadays, but also old
+dependencies and bad API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM-Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction the Model version 4.0.0 is used not only for the build, but also by consumers of the
+artifact.
+But several contents of the POM are only necessary for the build while others like the dependencies are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As names suggest the "Build-POM" will contain all information needed for to build the artifact, e.g. used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep those which are really needed to use the artifact, e.g. dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4 a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others got marked as deprecated.
+To not break the ecosystem this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as like every software update - it's suggested to update them to 4.1.0, e.g. to avoid problems when deprecated
+things get removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 till today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files the wording "Maven project" is used.
+However, project containing multiple parts, e.g. an API and a client, each of those parts was called "module" and listed
+in the `<modules>` section of the POM, leading to the terms of "multi-module project".
+This wording introduced some inconsistency, especially as projects with any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9 the term "module" raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>`analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency managing BOMs.
+While the new type is only available with model Version 4.1.0 the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2004][5].
+
+**Note**: With Maven 4 it's also possible to exclude dependencies which are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven4 importing BOMs with classifier is now possible.
+Therefore, Maven team suggests that projects BOMs be generated as classified artifacts (see Maven build "skinny" vs "
Review Comment:
```suggestion
Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts (see Maven build "skinny" vs "
```
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's new in Maven 4?
+
+Maven is over 20 years old and is one of the most used build-tool in the Java world.
+Since all the years one important rule was the highest backward-compatibility as possible, especially with
+its [POM-schema with Model version 4.0.0][2], used for the build itself, but also by consumers.
+This made Maven more than a tool, but a whole ecosystem with a lot of things depended on the POM, esp. the Maven Central
+repository, other build tools and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare to changes which are impossible nowadays, like a complete new build schema.
+
+Another pain point of Maven 3 is a code base with a lot of deprecated, convoluted, non performant and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebases contains old Java code that can be optimized nowadays, but also old
+dependencies and bad API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM-Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction the Model version 4.0.0 is used not only for the build, but also by consumers of the
+artifact.
+But several contents of the POM are only necessary for the build while others like the dependencies are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As names suggest the "Build-POM" will contain all information needed for to build the artifact, e.g. used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep those which are really needed to use the artifact, e.g. dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4 a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others got marked as deprecated.
+To not break the ecosystem this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as like every software update - it's suggested to update them to 4.1.0, e.g. to avoid problems when deprecated
+things get removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 till today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files the wording "Maven project" is used.
+However, project containing multiple parts, e.g. an API and a client, each of those parts was called "module" and listed
+in the `<modules>` section of the POM, leading to the terms of "multi-module project".
+This wording introduced some inconsistency, especially as projects with any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9 the term "module" raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>`analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency managing BOMs.
+While the new type is only available with model Version 4.1.0 the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2004][5].
+
+**Note**: With Maven 4 it's also possible to exclude dependencies which are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven4 importing BOMs with classifier is now possible.
Review Comment:
```suggestion
Also note that in Maven 4 importing BOMs with classifier is now possible.
```
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's new in Maven 4?
+
+Maven is over 20 years old and is one of the most used build-tool in the Java world.
+Since all the years one important rule was the highest backward-compatibility as possible, especially with
+its [POM-schema with Model version 4.0.0][2], used for the build itself, but also by consumers.
+This made Maven more than a tool, but a whole ecosystem with a lot of things depended on the POM, esp. the Maven Central
+repository, other build tools and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare to changes which are impossible nowadays, like a complete new build schema.
+
+Another pain point of Maven 3 is a code base with a lot of deprecated, convoluted, non performant and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebases contains old Java code that can be optimized nowadays, but also old
+dependencies and bad API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM-Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction the Model version 4.0.0 is used not only for the build, but also by consumers of the
+artifact.
+But several contents of the POM are only necessary for the build while others like the dependencies are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As names suggest the "Build-POM" will contain all information needed for to build the artifact, e.g. used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep those which are really needed to use the artifact, e.g. dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4 a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others got marked as deprecated.
+To not break the ecosystem this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as like every software update - it's suggested to update them to 4.1.0, e.g. to avoid problems when deprecated
+things get removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 till today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files the wording "Maven project" is used.
+However, project containing multiple parts, e.g. an API and a client, each of those parts was called "module" and listed
+in the `<modules>` section of the POM, leading to the terms of "multi-module project".
+This wording introduced some inconsistency, especially as projects with any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9 the term "module" raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>`analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency managing BOMs.
+While the new type is only available with model Version 4.1.0 the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2004][5].
+
+**Note**: With Maven 4 it's also possible to exclude dependencies which are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven4 importing BOMs with classifier is now possible.
+Therefore, Maven team suggests that projects BOMs be generated as classified artifacts (see Maven build "skinny" vs "
+fat" BOM).
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison about which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply for artefacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations, where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g. when
+condition based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Everytime a Maven build is executed it has to determine the projects root so identify things like the parent project,
+directory information and so on.
+To "help" Maven finding the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project specific configuration to run Maven, e.g. a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4 there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds the boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false) the directory of this POM file is considered the root directory.
+
+Another pain point in relation of the root directly is that until Maven 4 there was no official variable to make use of
+the root folder in your POM files, e.g. when you want to define the path to a `checkstyle-suppressions.xml` file for the
+checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined it should always have the same value for a given project, whereas the value of the`topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subprojects' own base directory, which was and is still accessibly via the `${basedir}` property for the usage in POM
+files and will always have a value.
+
+**Note:** In the past some people "hacked" workarounds for the`rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4 those "hacks" will most probably not work anymore, because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing central repository, the Build-POM should be
+able to evolve.
+This includes allowing the use of alternate syntaxes, by having Maven 4 providing a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects which uses this features is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected it's no longer required to define the parent versions in each subproject, when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parents and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partly supported usage of CI-friendly variables, e.g. `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4 no additional plugin is needed anymore, but full build-in support is provided.
+You can now use variables as versions in your configuration, e.g.
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by a `maven.config` file
+or as a parameter, e.g. `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent from one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuild too).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due the long-stand
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended to not use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully build subprojects when the overall build failed, and will skip to rebuild
+those if you resume the build.
+With Maven 4 it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g. Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve the daily work with those.
+Thanks to [MNG-6754][14] all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3 each subproject was having a different one.
+This should make it easier to identify the archives which belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in the situation where some (successfully
+build) subprojects where deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users are expecting:
+Only deploy when all subprojects were build successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK, but also comes with a more secure runtime as Java 17 includes more security features earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements, because you need to compile against or using another JDK, please have a look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was hold in March 2024, shortly before Java 22 was
+released.
+One reason Java 17 was chosen over Java 21, because it was (at this time) the second last Java version for which many
+vendors offer long-term-support.*
+
+### Application maintenance
+
+As with every update, especially major ones, large application maintenance happens, containing huge code, API and
+dependency updates and even removals.
+For example the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates contain not only usages of newer Java language features, but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing things that either never should have worked or were only kept for backward-compatibility
+already in Maven 3, e.g. using `${pom.*}` expressions.
+Maven own Super POM was also upgrading, which declares new default versions of Maven's core plugins.
+
+**Note**: Due upgrading the default versions of Maven plugins, your build might behave different that before, even if
+you didn't purposely change anything.
+To avoid this situation you should always define fixed versions of all the plugins you use!
+By doing this you are in control of your build - at the costs of being responsible to upgrade the versions yourself.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM!
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which will break the build when at least one log message
+matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument of a log level severity, e.g. `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so the `?` argument was added to the profile parameter.
+When using this the build won't break, but an information will be printed twice (at the start and the end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more and flexible ways to activate profiles, by providing condition based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3 the lifecycle was mathematical graph.
+This changed with Maven 4 where the lifecycle is defined as a tree of phases.
+This allows a more consistent execution of dependent phases, e.g. `compile` must execute after `compile-only` project
+dependencies have reached the `ready` phase, but also "skipping" phases (in comparison to the old graph), e.g. `deploy`
+an artifact without `install`ing it to the user repository.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before` and `after` phase, allowing plugins to bind themselves to those by adding their
+prefixes to the name of the main phase name.
+For example, if you want to set up test data before running your integration test you could execute stuff during the
+`before-integration-test` phase.
+
+If this is not enough, maybe because you want to do multiple things inside the same phase, you can order each execution
+inside a phase by using square brackets with an Integer at the end of the phase name, e.g.
+
+```
+before-integration-test[100]
+before-integration-test[200]
+```
+
+**Warning**: The conceptional `pre-*` and `post-*` phases, wich were only available to selected phases and homogeneously
+named are deprecated - don't use them (anymore)!
+This becomes even more important when you were binding a plugin to the `post-*` phase of a lifecycle phase, because the
+`pre-*` phase of the phase you really would like to bind to did not exist, e.g. binding to `process-resources` phase,
+because there was no `pre-compile`one.
+
+## Maven plugins, security and tools
+
+### Maven plugins
+
+As written above Maven 4 will contain huge code and API updates, resulting in breaking (very) old Maven plugins, which
+were not updated to the recommended APIs.
+Major changes regarding plugins contain a now proper immutable plugin model together with a changed plugin API.
+The updated API provides hints as a preparation for Maven 4.
+You can enable them passing the following argument to your build: `-Dmaven.plugin.validation=verbose`.
+You should also only rely on the official Maven BOMs when developing plugins.
+If a plugin still relies on long time deprecated and now removed Plexus dependency resolution, it will no longer work
+and needs to be updated to JSR-330 - see [Maven & JSR-330][26] for further information.
+
+**Advice**: If you are maintaining a Maven plugin, you should test it with Maven 3.9.x, have a close look at upcoming
+warnings and update the plugin.
+
+### Improved encryption
+
+Security is important and storing unencrypted passwords is bad.
+Maven 3's password encryption has several serious issues and could rather be call a “password obfuscation”.
+Maven 4 instead got a fully redone encryption, based on Maven Encryption (`mvnenc`) - a standalone CLI tool.
+As for now it provides functionally equivalent operations as Maven 3 (see ["Maven: Password Encryption"][30]), but adds
+improvements like a `decrypt` functionality.
+A brought overview about the problems in Maven 3 and the solution in Maven 4 can be found in the
+article ["Handling sensitive data in Maven"][31] by Maven maintainer Tamás Cservenák.
+
+### Maven Resolver
+
+The [Maven Artifact Resolver][28] is a library for working with artifact repositories and dependency resolution.
+Maven 4 will include the new 2.0 release of this library, which contains more than 150 fixes, upgrades and improvements,
+e.g. a Java native HTTP-Client - thanks to lift of the Java version to JDK 17!
+See the project page for more information!
Review Comment:
I would suggest to make this a link, or remove this line. If you go for a link, I would suggest to remove the exclamation mark.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's new in Maven 4?
+
+Maven is over 20 years old and is one of the most used build-tool in the Java world.
+Since all the years one important rule was the highest backward-compatibility as possible, especially with
+its [POM-schema with Model version 4.0.0][2], used for the build itself, but also by consumers.
+This made Maven more than a tool, but a whole ecosystem with a lot of things depended on the POM, esp. the Maven Central
+repository, other build tools and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare to changes which are impossible nowadays, like a complete new build schema.
+
+Another pain point of Maven 3 is a code base with a lot of deprecated, convoluted, non performant and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebases contains old Java code that can be optimized nowadays, but also old
+dependencies and bad API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM-Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction the Model version 4.0.0 is used not only for the build, but also by consumers of the
+artifact.
+But several contents of the POM are only necessary for the build while others like the dependencies are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As names suggest the "Build-POM" will contain all information needed for to build the artifact, e.g. used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep those which are really needed to use the artifact, e.g. dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4 a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others got marked as deprecated.
+To not break the ecosystem this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as like every software update - it's suggested to update them to 4.1.0, e.g. to avoid problems when deprecated
+things get removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 till today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files the wording "Maven project" is used.
+However, project containing multiple parts, e.g. an API and a client, each of those parts was called "module" and listed
+in the `<modules>` section of the POM, leading to the terms of "multi-module project".
+This wording introduced some inconsistency, especially as projects with any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9 the term "module" raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>`analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency managing BOMs.
+While the new type is only available with model Version 4.1.0 the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2004][5].
+
+**Note**: With Maven 4 it's also possible to exclude dependencies which are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven4 importing BOMs with classifier is now possible.
+Therefore, Maven team suggests that projects BOMs be generated as classified artifacts (see Maven build "skinny" vs "
+fat" BOM).
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison about which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply for artefacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations, where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g. when
+condition based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Everytime a Maven build is executed it has to determine the projects root so identify things like the parent project,
+directory information and so on.
+To "help" Maven finding the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project specific configuration to run Maven, e.g. a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4 there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds the boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false) the directory of this POM file is considered the root directory.
+
+Another pain point in relation of the root directly is that until Maven 4 there was no official variable to make use of
+the root folder in your POM files, e.g. when you want to define the path to a `checkstyle-suppressions.xml` file for the
+checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined it should always have the same value for a given project, whereas the value of the`topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subprojects' own base directory, which was and is still accessibly via the `${basedir}` property for the usage in POM
+files and will always have a value.
+
+**Note:** In the past some people "hacked" workarounds for the`rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4 those "hacks" will most probably not work anymore, because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing central repository, the Build-POM should be
+able to evolve.
+This includes allowing the use of alternate syntaxes, by having Maven 4 providing a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects which uses this features is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected it's no longer required to define the parent versions in each subproject, when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parents and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partly supported usage of CI-friendly variables, e.g. `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4 no additional plugin is needed anymore, but full build-in support is provided.
+You can now use variables as versions in your configuration, e.g.
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by a `maven.config` file
+or as a parameter, e.g. `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent from one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuild too).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due the long-stand
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended to not use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully build subprojects when the overall build failed, and will skip to rebuild
+those if you resume the build.
+With Maven 4 it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g. Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve the daily work with those.
+Thanks to [MNG-6754][14] all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3 each subproject was having a different one.
+This should make it easier to identify the archives which belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in the situation where some (successfully
+build) subprojects where deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users are expecting:
+Only deploy when all subprojects were build successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK, but also comes with a more secure runtime as Java 17 includes more security features earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements, because you need to compile against or using another JDK, please have a look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was hold in March 2024, shortly before Java 22 was
+released.
+One reason Java 17 was chosen over Java 21, because it was (at this time) the second last Java version for which many
+vendors offer long-term-support.*
+
+### Application maintenance
+
+As with every update, especially major ones, large application maintenance happens, containing huge code, API and
+dependency updates and even removals.
+For example the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates contain not only usages of newer Java language features, but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing things that either never should have worked or were only kept for backward-compatibility
+already in Maven 3, e.g. using `${pom.*}` expressions.
+Maven own Super POM was also upgrading, which declares new default versions of Maven's core plugins.
+
+**Note**: Due upgrading the default versions of Maven plugins, your build might behave different that before, even if
+you didn't purposely change anything.
+To avoid this situation you should always define fixed versions of all the plugins you use!
+By doing this you are in control of your build - at the costs of being responsible to upgrade the versions yourself.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM!
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which will break the build when at least one log message
+matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument of a log level severity, e.g. `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so the `?` argument was added to the profile parameter.
+When using this the build won't break, but an information will be printed twice (at the start and the end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more and flexible ways to activate profiles, by providing condition based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3 the lifecycle was mathematical graph.
+This changed with Maven 4 where the lifecycle is defined as a tree of phases.
+This allows a more consistent execution of dependent phases, e.g. `compile` must execute after `compile-only` project
+dependencies have reached the `ready` phase, but also "skipping" phases (in comparison to the old graph), e.g. `deploy`
+an artifact without `install`ing it to the user repository.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before` and `after` phase, allowing plugins to bind themselves to those by adding their
+prefixes to the name of the main phase name.
+For example, if you want to set up test data before running your integration test you could execute stuff during the
+`before-integration-test` phase.
+
+If this is not enough, maybe because you want to do multiple things inside the same phase, you can order each execution
+inside a phase by using square brackets with an Integer at the end of the phase name, e.g.
+
+```
+before-integration-test[100]
+before-integration-test[200]
+```
+
+**Warning**: The conceptional `pre-*` and `post-*` phases, wich were only available to selected phases and homogeneously
+named are deprecated - don't use them (anymore)!
+This becomes even more important when you were binding a plugin to the `post-*` phase of a lifecycle phase, because the
+`pre-*` phase of the phase you really would like to bind to did not exist, e.g. binding to `process-resources` phase,
+because there was no `pre-compile`one.
+
+## Maven plugins, security and tools
+
+### Maven plugins
+
+As written above Maven 4 will contain huge code and API updates, resulting in breaking (very) old Maven plugins, which
+were not updated to the recommended APIs.
+Major changes regarding plugins contain a now proper immutable plugin model together with a changed plugin API.
+The updated API provides hints as a preparation for Maven 4.
+You can enable them passing the following argument to your build: `-Dmaven.plugin.validation=verbose`.
+You should also only rely on the official Maven BOMs when developing plugins.
+If a plugin still relies on long time deprecated and now removed Plexus dependency resolution, it will no longer work
+and needs to be updated to JSR-330 - see [Maven & JSR-330][26] for further information.
+
+**Advice**: If you are maintaining a Maven plugin, you should test it with Maven 3.9.x, have a close look at upcoming
+warnings and update the plugin.
+
+### Improved encryption
+
+Security is important and storing unencrypted passwords is bad.
+Maven 3's password encryption has several serious issues and could rather be call a “password obfuscation”.
+Maven 4 instead got a fully redone encryption, based on Maven Encryption (`mvnenc`) - a standalone CLI tool.
+As for now it provides functionally equivalent operations as Maven 3 (see ["Maven: Password Encryption"][30]), but adds
+improvements like a `decrypt` functionality.
+A brought overview about the problems in Maven 3 and the solution in Maven 4 can be found in the
+article ["Handling sensitive data in Maven"][31] by Maven maintainer Tamás Cservenák.
+
+### Maven Resolver
+
+The [Maven Artifact Resolver][28] is a library for working with artifact repositories and dependency resolution.
+Maven 4 will include the new 2.0 release of this library, which contains more than 150 fixes, upgrades and improvements,
+e.g. a Java native HTTP-Client - thanks to lift of the Java version to JDK 17!
+See the project page for more information!
+
+### Maven Shell
+
+When you run any `mvn` the full chain of booting Java, Maven, load config, do the work, tear down and exit the process
+is done - **every single time**.
+To improve performance and reduce build time you can use the [Maven Daemon][29] (`mvnd`), which manages a pool of N
+resident Maven processes.
+With Maven 4 you can also use the brightly polished "Maven Shell" (`mvnsh`), which will keep exactly one resident Maven
+process as long as the shell is opened.
+Stay tuned for more information about this!
Review Comment:
If there is no more information available, I would not mention this. We can always update the article when there is a more detailed blog/video/resource available.
```suggestion
Stay tuned for more information about this!
```
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's new in Maven 4?
+
+Maven is over 20 years old and is one of the most used build-tool in the Java world.
+Since all the years one important rule was the highest backward-compatibility as possible, especially with
+its [POM-schema with Model version 4.0.0][2], used for the build itself, but also by consumers.
+This made Maven more than a tool, but a whole ecosystem with a lot of things depended on the POM, esp. the Maven Central
+repository, other build tools and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare to changes which are impossible nowadays, like a complete new build schema.
+
+Another pain point of Maven 3 is a code base with a lot of deprecated, convoluted, non performant and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebases contains old Java code that can be optimized nowadays, but also old
+dependencies and bad API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM-Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction the Model version 4.0.0 is used not only for the build, but also by consumers of the
+artifact.
+But several contents of the POM are only necessary for the build while others like the dependencies are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As names suggest the "Build-POM" will contain all information needed for to build the artifact, e.g. used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep those which are really needed to use the artifact, e.g. dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4 a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others got marked as deprecated.
+To not break the ecosystem this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as like every software update - it's suggested to update them to 4.1.0, e.g. to avoid problems when deprecated
+things get removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 till today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files the wording "Maven project" is used.
+However, project containing multiple parts, e.g. an API and a client, each of those parts was called "module" and listed
+in the `<modules>` section of the POM, leading to the terms of "multi-module project".
+This wording introduced some inconsistency, especially as projects with any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9 the term "module" raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>`analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency managing BOMs.
+While the new type is only available with model Version 4.1.0 the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2004][5].
+
+**Note**: With Maven 4 it's also possible to exclude dependencies which are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven4 importing BOMs with classifier is now possible.
+Therefore, Maven team suggests that projects BOMs be generated as classified artifacts (see Maven build "skinny" vs "
Review Comment:
Apart from the grammar, I'm not sure what this means. I hope somebody else can clarify?
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's new in Maven 4?
+
+Maven is over 20 years old and is one of the most used build-tool in the Java world.
+Since all the years one important rule was the highest backward-compatibility as possible, especially with
+its [POM-schema with Model version 4.0.0][2], used for the build itself, but also by consumers.
+This made Maven more than a tool, but a whole ecosystem with a lot of things depended on the POM, esp. the Maven Central
+repository, other build tools and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare to changes which are impossible nowadays, like a complete new build schema.
+
+Another pain point of Maven 3 is a code base with a lot of deprecated, convoluted, non performant and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebases contains old Java code that can be optimized nowadays, but also old
+dependencies and bad API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM-Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction the Model version 4.0.0 is used not only for the build, but also by consumers of the
+artifact.
+But several contents of the POM are only necessary for the build while others like the dependencies are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As names suggest the "Build-POM" will contain all information needed for to build the artifact, e.g. used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep those which are really needed to use the artifact, e.g. dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4 a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others got marked as deprecated.
+To not break the ecosystem this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as like every software update - it's suggested to update them to 4.1.0, e.g. to avoid problems when deprecated
+things get removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 till today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files the wording "Maven project" is used.
+However, project containing multiple parts, e.g. an API and a client, each of those parts was called "module" and listed
+in the `<modules>` section of the POM, leading to the terms of "multi-module project".
+This wording introduced some inconsistency, especially as projects with any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9 the term "module" raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>`analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency managing BOMs.
+While the new type is only available with model Version 4.1.0 the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2004][5].
+
+**Note**: With Maven 4 it's also possible to exclude dependencies which are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven4 importing BOMs with classifier is now possible.
+Therefore, Maven team suggests that projects BOMs be generated as classified artifacts (see Maven build "skinny" vs "
+fat" BOM).
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison about which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply for artefacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations, where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g. when
+condition based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Everytime a Maven build is executed it has to determine the projects root so identify things like the parent project,
+directory information and so on.
+To "help" Maven finding the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project specific configuration to run Maven, e.g. a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4 there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds the boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false) the directory of this POM file is considered the root directory.
+
+Another pain point in relation of the root directly is that until Maven 4 there was no official variable to make use of
+the root folder in your POM files, e.g. when you want to define the path to a `checkstyle-suppressions.xml` file for the
+checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined it should always have the same value for a given project, whereas the value of the`topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subprojects' own base directory, which was and is still accessibly via the `${basedir}` property for the usage in POM
+files and will always have a value.
+
+**Note:** In the past some people "hacked" workarounds for the`rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4 those "hacks" will most probably not work anymore, because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing central repository, the Build-POM should be
+able to evolve.
+This includes allowing the use of alternate syntaxes, by having Maven 4 providing a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects which uses this features is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected it's no longer required to define the parent versions in each subproject, when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parents and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partly supported usage of CI-friendly variables, e.g. `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4 no additional plugin is needed anymore, but full build-in support is provided.
+You can now use variables as versions in your configuration, e.g.
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by a `maven.config` file
+or as a parameter, e.g. `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent from one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuild too).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due the long-stand
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended to not use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully build subprojects when the overall build failed, and will skip to rebuild
+those if you resume the build.
+With Maven 4 it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g. Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve the daily work with those.
+Thanks to [MNG-6754][14] all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3 each subproject was having a different one.
+This should make it easier to identify the archives which belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in the situation where some (successfully
+build) subprojects where deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users are expecting:
+Only deploy when all subprojects were build successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK, but also comes with a more secure runtime as Java 17 includes more security features earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements, because you need to compile against or using another JDK, please have a look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was hold in March 2024, shortly before Java 22 was
+released.
+One reason Java 17 was chosen over Java 21, because it was (at this time) the second last Java version for which many
+vendors offer long-term-support.*
+
+### Application maintenance
+
+As with every update, especially major ones, large application maintenance happens, containing huge code, API and
+dependency updates and even removals.
+For example the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates contain not only usages of newer Java language features, but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing things that either never should have worked or were only kept for backward-compatibility
+already in Maven 3, e.g. using `${pom.*}` expressions.
+Maven own Super POM was also upgrading, which declares new default versions of Maven's core plugins.
+
+**Note**: Due upgrading the default versions of Maven plugins, your build might behave different that before, even if
+you didn't purposely change anything.
+To avoid this situation you should always define fixed versions of all the plugins you use!
+By doing this you are in control of your build - at the costs of being responsible to upgrade the versions yourself.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM!
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which will break the build when at least one log message
+matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument of a log level severity, e.g. `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so the `?` argument was added to the profile parameter.
+When using this the build won't break, but an information will be printed twice (at the start and the end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more and flexible ways to activate profiles, by providing condition based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3 the lifecycle was mathematical graph.
+This changed with Maven 4 where the lifecycle is defined as a tree of phases.
+This allows a more consistent execution of dependent phases, e.g. `compile` must execute after `compile-only` project
+dependencies have reached the `ready` phase, but also "skipping" phases (in comparison to the old graph), e.g. `deploy`
+an artifact without `install`ing it to the user repository.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before` and `after` phase, allowing plugins to bind themselves to those by adding their
+prefixes to the name of the main phase name.
+For example, if you want to set up test data before running your integration test you could execute stuff during the
+`before-integration-test` phase.
+
+If this is not enough, maybe because you want to do multiple things inside the same phase, you can order each execution
+inside a phase by using square brackets with an Integer at the end of the phase name, e.g.
+
+```
+before-integration-test[100]
+before-integration-test[200]
+```
+
+**Warning**: The conceptional `pre-*` and `post-*` phases, wich were only available to selected phases and homogeneously
+named are deprecated - don't use them (anymore)!
+This becomes even more important when you were binding a plugin to the `post-*` phase of a lifecycle phase, because the
+`pre-*` phase of the phase you really would like to bind to did not exist, e.g. binding to `process-resources` phase,
+because there was no `pre-compile`one.
+
+## Maven plugins, security and tools
+
+### Maven plugins
+
+As written above Maven 4 will contain huge code and API updates, resulting in breaking (very) old Maven plugins, which
+were not updated to the recommended APIs.
+Major changes regarding plugins contain a now proper immutable plugin model together with a changed plugin API.
+The updated API provides hints as a preparation for Maven 4.
+You can enable them passing the following argument to your build: `-Dmaven.plugin.validation=verbose`.
+You should also only rely on the official Maven BOMs when developing plugins.
+If a plugin still relies on long time deprecated and now removed Plexus dependency resolution, it will no longer work
+and needs to be updated to JSR-330 - see [Maven & JSR-330][26] for further information.
+
+**Advice**: If you are maintaining a Maven plugin, you should test it with Maven 3.9.x, have a close look at upcoming
+warnings and update the plugin.
+
+### Improved encryption
+
+Security is important and storing unencrypted passwords is bad.
+Maven 3's password encryption has several serious issues and could rather be call a “password obfuscation”.
+Maven 4 instead got a fully redone encryption, based on Maven Encryption (`mvnenc`) - a standalone CLI tool.
+As for now it provides functionally equivalent operations as Maven 3 (see ["Maven: Password Encryption"][30]), but adds
+improvements like a `decrypt` functionality.
+A brought overview about the problems in Maven 3 and the solution in Maven 4 can be found in the
Review Comment:
```suggestion
A broad overview about the problems in Maven 3 and the solution in Maven 4 can be found in the
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894404613
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,459 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially with
+its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven Central
+repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module" and listed
+in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a fully Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use of
+the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for the
+checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should be
+able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config` file
+or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements because you need to compile against or use another JDK, please look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was held in March 2024, shortly before Java 22 was
+released. One reason Java 17 was chosen over Java 21 was that it was (at this time) the second-last Java version for which many
+vendors offer long-term support.*
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates and even removals.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only the use of newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even if
+you didn't purposely change anything.
+To avoid this situation, you should always define fixed versions of all the plugins you use!
+By doing this, you are in control of your build - at the cost of being responsible for upgrading the versions yourself.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM!
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which will break the build when at least one log message
+matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, e.g., `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break; instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3, the lifecycle was a mathematical graph.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more consistent execution of dependent phases, e.g., `compile` must execute after `compile-only` project
+dependencies have reached the `ready` phase, and also allows "skipping" phases (in comparison to the old graph), e.g., `deploy`
+an artifact without `install`ing it to the user repository.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before` and `after` phase, allowing plugins to bind themselves to those by adding their
+prefixes to the name of the main phase.
+For example, if you want to set up test data before running your integration tests, you could execute tasks during the
+`before-integration-test` phase.
+
+If this is not enough, perhaps because you want to do multiple things inside the same phase, you can order each execution
+inside a phase by using square brackets with an integer at the end of the phase name, e.g.,
+
+```
+before-integration-test[100]
+before-integration-test[200]
+```
+
+**Warning**: The conceptual `pre-*` and `post-*` phases, which were only available for selected phases and had inconsistent
+naming, are deprecated - don't use them (anymore)!
+This becomes even more important if you were binding a plugin to the `post-*` phase of a lifecycle phase because the
+`pre-*` phase of the phase you really wanted to bind to did not exist, e.g., binding to `process-resources` phase
+because there was no `pre-compile` phase.
+
+## Maven plugins, security and tools
+
+### Maven plugins
+
+As mentioned above, Maven 4 will contain significant code and API updates, resulting in breaking changes for (very) old Maven plugins that
+were not updated to use the recommended APIs.
+Major changes regarding plugins include a proper immutable plugin model together with a revised plugin API.
+The updated API provides hints as preparation for Maven 4.
+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.
+If a plugin still relies on long-deprecated and now removed Plexus dependency resolution, it will no longer work
+and needs to be updated to use JSR-330 - see [Maven & JSR-330][26] for further information.
+
+**Advice**: If you are maintaining a Maven plugin, you should test it with Maven 3.9.x, pay close attention to upcoming
+warnings, and update the plugin accordingly.
+
+### Improved encryption
+
+Security is important, and storing unencrypted passwords is bad practice.
+Maven 3's password encryption had several serious issues and could more accurately be called "password obfuscation".
+Maven 4 instead has a completely redone encryption system, based on Maven Encryption (`mvnenc`) - a standalone CLI tool.
+As of now, it provides functionally equivalent operations as Maven 3 (see ["Maven: Password Encryption"][30]) but adds
+improvements like a `decrypt` functionality.
+A broad overview of the problems in Maven 3 and the solution in Maven 4 can be found in the
+article ["Handling sensitive data in Maven"][31] by Maven maintainer Tamás Cservenák.
+
+### Maven Resolver
+
+The [Maven Artifact Resolver][28] is a library for working with artifact repositories and dependency resolution.
+Maven 4 will include the new 2.0 release of this library, which contains more than 150 fixes, upgrades, and improvements,
+e.g., a Java native HTTP-Client - thanks to raising the Java version requirement to JDK 17!
Review Comment:
Added. I would like to write another article about plugin changes, but I will need help with that in terms of "you tell me what to write" as I have almost no clue about plugin development yet.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "elharo (via GitHub)" <gi...@apache.org>.
elharo commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1898686052
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
Review Comment:
delete "But this stable schema comes at a price - the lack of flexibility."
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1898706000
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicate code
+which costs the volunteers who maintain Maven a lot of time.
+This means that the Maven codebase contains not only old Java code that can be optimized nowadays but also old
Review Comment:
Removed the part "that can be optimized nowadays". Hope this pleases you better now.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1898725633
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
Review Comment:
According to what [Oracles writes about Security updates](https://docs.oracle.com/en/java/javase/22/migrate/security-updates.html#GUID-9C6409FA-3EE2-4717-A1B4-B9A01690C081) I think this sentences is not wrong.
But yeah it's a little bit of "manager buzzword game" 👼
(Ana Maria Mihalcean also has a talk [From Java 17 to 21: A Showcase of JDK Security Enhancement] about this, but focusing more on security features between 17 and 21, which do not apply to Maven 4 when considering using a JDK 17 only).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on PR #598:
URL: https://github.com/apache/maven-site/pull/598#issuecomment-2685576374
This huge PR has been stale some time. From time to time someone has comments about minor parts of the article, others have already approved it.
As we can easily update the page when things change (added a note about that), I will merge this PR so the information are visible for the community.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "kwin (via GitHub)" <gi...@apache.org>.
kwin commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1931964792
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,477 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is the most widely used build tool in the Java world.
+Throughout the years, Maven has maintained backward compatibility, especially of its [POM file][2] with Model version
+4.0.0.
+
+The POM file fulfills two needs.
+First, the POM holds all the information and configuration, which are needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, for example dependencies, which are needed by projects which depend on the
+artifact.
+These dependent projects are called the "consumers".
+
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+Thus, any change in the POM's schema forces each participant of the ecosystem to either adopt the change or drop
+support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+In order for Maven to evolve, it's necessary to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## Required Java version
+
+Maven 4 requires Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 is only needed to **run Maven**!
+You can still compile against older Java versions using the same [compiler plugin configuration][6] as before.
+If you need to compile against or use another JDK, see the [Guide to Using Toolchains][7] (or the
+article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten Mulders).
+
+## POM Changes
+
+### Consumer POM
+
+Maven 4 generates a stripped down consumer POM that removes build information not needed by consumers, and deploys this
+to the remote repository.
+It does not deploy the `pom.xml` used to build the project.
+
+### Model version 4.1.0
+
+Maven 4 updates the POM version to 4.1.0 which defines the namespace `http://maven.apache.org/POM/4.1.0`.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the build POM, while the consumer POM will still use
+version 4.0.0.
+Maven generates the consumer POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 if you don't need to use the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project built with Maven.
+The [top level directory][32] of a Maven project contains at least the source folder `src` and the project's POM file
+`pom.xml`.
+A Maven project may have other Maven projects within subdirectories, each with its own `pom.xml` file.
+Each project within a subdirectory is called a "subproject".
+
+Example: Project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects unless they are linked from the root POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+Projects which have at least one subproject are called "multi-module projects", while those which do not have any
+subprojects are called "single module projects".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated `bom` packaging type to provide a [Bill of Materials BOM][4].
+This now differentiates between parent POMs and dependency-managing BOMs.
+The new type is only available as a build POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible consumer POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build.
+In other words: you should only import external BOMs.
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing build POM and consumer POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "consumer POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, for example plugin configuration!
+* Some of the build-related content which is (as of now) still available in the consumer POM might be available only in
+ the build POM in the future.
+
+| Content | Build POM | Consumer POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a consumer POM based on version 4.1.0, for example
+when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, for example a `maven.config` or
+`jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the build POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, for example when you want to define the path to a `checkstyle-suppressions.xml`
+file for the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+current working directory.
+The `rootDirectory` can only contain a value when either a `.mvn` directory is defined or the `root` attribute is set to
+true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4 those properties were removed or marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 consumer POM is set in stone, the build POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, like `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration.
+
+Example
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, for example `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects can cause confusion in Maven 3.
+When the build of subproject B, which requires subproject A, is failing for whatever reason, Maven 3 is telling
+the user to fix the error and then resume the build with `--resume-from :<nameOfTheFailingSubproject>`.
+But doing this instantly fails the build again, because the required subproject A couldn't be found (as it was not
+rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (for example Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where successfully
+built subprojects were deployed to the (local or remote) repository, but failed subprojects were not.
+This was finally changed in Maven 4 to what most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+in Maven 3, for example using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, always define fixed versions of all the plugins you use.
+By doing this, you are in control of your build.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM.
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which breaks the build when the severity of at least one log
+message matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, for example, `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break.
+Instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+In Maven 3 the lifecycle is an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more fine-grained execution of dependent phases.
+For example, the `compile` phase must execute after `compile-only` project dependencies have reached the `ready` phase.
+Maven 4 also allows to skip phases (in comparison to the old graph).
+For example, it's possible to `deploy` an artifact without `install`ing it to the user repository.
+
+For compatibility, the execution behavior is not really changed by default compared to Maven 3.
+In order to actually leverage the new tree-based lifecycle, the user has to enable the concurrent builder using
+`-b concurrent`.
+Running with the concurrent builder will allow finer grained dependency instead of the usual Maven 3 per-project
+dependency.
+With the usual builders and run `mvn verify`, a project will run up to the verify phase, before a dependent project can
+start being built, whereas the concurrent builder will allow a dependant project to be built as soon as the dependencies
+are at the `ready` phase.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before:` and an `after:` phase, allowing plugins to bind themselves to those.
+For example, if you want to set up test data before running your integration tests, you could execute tasks during the
+`before:integration-test` phase.
+
+If this is not enough, perhaps because you want to do multiple things inside the same phase, you can order each
+execution inside a phase by using square brackets with an integer at the end of the phase name.
+
+Example
+
+```
+before:integration-test[100]
+before:integration-test[200]
+```
+
+**Warning**: The conceptual `pre-*` and `post-*` phases, which were only available for selected phases and had
+inconsistent naming, are deprecated.
+Don't use them!
+This becomes even more important if you are binding a plugin to the `post-*` phase of a lifecycle phase because the
+`pre-*` phase of the phase you really want to bind to does not exist, for example, binding to `process-resources` phase
+because there was no `pre-compile` phase.
+
+## Maven plugins, security, and tools
+
+### Maven plugins
+
+As mentioned above, Maven 4 contains significant code and API updates, resulting in breaking changes for (very) old
+Maven plugins that have not been updated to use the recommended APIs.
+Major changes regarding plugins include a proper immutable plugin model together with a revised plugin API.
+The updated API provides hints as preparation for Maven 4.
+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.
+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.
+
+**Advice**: If you are maintaining a Maven plugin, you should test it with Maven 3.9.x.
+Pay close attention to upcoming warnings and update the plugin accordingly.
+
+### Improved encryption
+
+Security is important, and storing unencrypted passwords is bad practice.
+Maven 3's password encryption had several serious issues and could more accurately be called "password obfuscation".
+Maven 4 instead has a completely redone encryption system, based on Maven Encryption (`mvnenc`) - a standalone CLI tool.
Review Comment:
But `based on Maven Encryption (`mvnenc`) - a standalone CLI tool.` feels wrong to me. I would rather remove the sentence then altogether.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "cstamas (via GitHub)" <gi...@apache.org>.
cstamas commented on PR #598:
URL: https://github.com/apache/maven-site/pull/598#issuecomment-2593432314
This PR is for big page (long content) that is to be published without any predecessor, and PR goes for over a month now with long discussions that is hard to track.
Why not just merge it, and continue improving it factually and stylistically in step by step instead?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "elharo (via GitHub)" <gi...@apache.org>.
elharo commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1917052351
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,465 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
Review Comment:
no break after the quote mark
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,465 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version adds some new elements and attributes, while others are marked as deprecated.
Review Comment:
This version --> Version 4.1.0
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,465 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
Review Comment:
Swap this and the next sentence.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,465 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
Review Comment:
All projects contain multiple parts. What you need to say here is that a project containing multiple pom files in subdirectories has one subproject per pom. Maybe something like,
When a project com.foo:A contains a directory that has its own pom.xml file for com.foo:B we say that B is a subproject of A.
This is tricky, but it's important to be precise.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,465 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
Review Comment:
Maven 4 introduces a new POM version 4.1.0.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
Review Comment:
Maybe try rewriting all this as "A Maven project is _____" and fill in the blank.
I generally don't consider the build folder ot be part of mavcen project, but do consider the src and test folders to be part of the project.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,465 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
Review Comment:
naming "modules" as what they are - subprojects.
-->
renaming modules to projects and submodules to subprojects.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "elharo (via GitHub)" <gi...@apache.org>.
elharo commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1915625974
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,496 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+On the one side, the POM holds all the information and configuration, which are only needed to build the artifact.
Review Comment:
On the on side --> First
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,496 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+On the one side, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact was created, these build information are not relevant anymore.
+On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use
+the artifact, e.g. dependencies.
Review Comment:
delete ", e.g. dependencies" as it confuses the dependent with the dependencies
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,496 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+On the one side, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact was created, these build information are not relevant anymore.
+On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use
+the artifact, e.g. dependencies.
+These dependent projects, which "consume" an artifact (and its POM), are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation, that any change in the POM's schema forces each participant of the ecosystem to either
Review Comment:
situation, that --> situation that
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,496 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+On the one side, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact was created, these build information are not relevant anymore.
+On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use
+the artifact, e.g. dependencies.
+These dependent projects, which "consume" an artifact (and its POM), are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation, that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+So Maven's POM file got cemented, not able to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from those needed by the
+consumers, but without breaking in the ecosystem.
+Maven 4 will prepare for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only by the build but also by consumers of the
+artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., applied plugins
Review Comment:
will contain --> contains
It's likely this doc exists in the same time frame as Maven 4 so use present tense when describing it
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
Review Comment:
Are these Java system properties?
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,496 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+On the one side, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact was created, these build information are not relevant anymore.
+On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use
+the artifact, e.g. dependencies.
+These dependent projects, which "consume" an artifact (and its POM), are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation, that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+So Maven's POM file got cemented, not able to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from those needed by the
+consumers, but without breaking in the ecosystem.
+Maven 4 will prepare for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only by the build but also by consumers of the
+artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+directory is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those properties were removed
+or at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone, the Build-POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, e.g., `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`, but `mvn verify` for your regular builds!**
Review Comment:
, but --> . Instead
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,496 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+On the one side, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact was created, these build information are not relevant anymore.
+On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use
+the artifact, e.g. dependencies.
+These dependent projects, which "consume" an artifact (and its POM), are called the "consumers" (of an artifact).
Review Comment:
delete "which "consume" an artifact (and its POM),"
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,496 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+On the one side, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact was created, these build information are not relevant anymore.
+On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use
+the artifact, e.g. dependencies.
+These dependent projects, which "consume" an artifact (and its POM), are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation, that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+So Maven's POM file got cemented, not able to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from those needed by the
+consumers, but without breaking in the ecosystem.
Review Comment:
in the --> the
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,496 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+On the one side, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact was created, these build information are not relevant anymore.
Review Comment:
After the artifact is created, this build information is not relevant anymore.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,496 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+On the one side, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact was created, these build information are not relevant anymore.
+On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use
Review Comment:
On then other side --> Second
no comma after projects
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,496 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+On the one side, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact was created, these build information are not relevant anymore.
+On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use
+the artifact, e.g. dependencies.
+These dependent projects, which "consume" an artifact (and its POM), are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation, that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+So Maven's POM file got cemented, not able to change.
Review Comment:
Thus the Maven POM syntax became fixed, unable to change.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,496 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+On the one side, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact was created, these build information are not relevant anymore.
+On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use
+the artifact, e.g. dependencies.
+These dependent projects, which "consume" an artifact (and its POM), are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation, that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+So Maven's POM file got cemented, not able to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from those needed by the
+consumers, but without breaking in the ecosystem.
+Maven 4 will prepare for this and more.
Review Comment:
will prepare --> prepares
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,496 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+On the one side, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact was created, these build information are not relevant anymore.
+On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use
+the artifact, e.g. dependencies.
+These dependent projects, which "consume" an artifact (and its POM), are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation, that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+So Maven's POM file got cemented, not able to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from those needed by the
+consumers, but without breaking in the ecosystem.
+Maven 4 will prepare for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only by the build but also by consumers of the
+artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+directory is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those properties were removed
+or at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone, the Build-POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, e.g., `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
Review Comment:
was dependent --> depended
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,496 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+On the one side, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact was created, these build information are not relevant anymore.
+On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use
+the artifact, e.g. dependencies.
+These dependent projects, which "consume" an artifact (and its POM), are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation, that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+So Maven's POM file got cemented, not able to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from those needed by the
+consumers, but without breaking in the ecosystem.
+Maven 4 will prepare for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only by the build but also by consumers of the
Review Comment:
Delete "As written in the introduction, "
It's important to note that model version 4.0.0 is what's used by Maven 3 and model version 4.1 is used by Maven 4 since this is surprising.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,496 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+On the one side, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact was created, these build information are not relevant anymore.
+On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use
+the artifact, e.g. dependencies.
+These dependent projects, which "consume" an artifact (and its POM), are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation, that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+So Maven's POM file got cemented, not able to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from those needed by the
Review Comment:
those --> the information
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,496 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+On the one side, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact was created, these build information are not relevant anymore.
+On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use
+the artifact, e.g. dependencies.
+These dependent projects, which "consume" an artifact (and its POM), are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation, that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+So Maven's POM file got cemented, not able to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from those needed by the
+consumers, but without breaking in the ecosystem.
+Maven 4 will prepare for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only by the build but also by consumers of the
+artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary.
Review Comment:
necassary for ????
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,496 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+On the one side, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact was created, these build information are not relevant anymore.
+On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use
+the artifact, e.g. dependencies.
+These dependent projects, which "consume" an artifact (and its POM), are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation, that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+So Maven's POM file got cemented, not able to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from those needed by the
+consumers, but without breaking in the ecosystem.
+Maven 4 will prepare for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only by the build but also by consumers of the
+artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
Review Comment:
will therefore differentiate --> therefore differentiates
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,496 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+On the one side, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact was created, these build information are not relevant anymore.
+On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use
+the artifact, e.g. dependencies.
+These dependent projects, which "consume" an artifact (and its POM), are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation, that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+So Maven's POM file got cemented, not able to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from those needed by the
+consumers, but without breaking in the ecosystem.
+Maven 4 will prepare for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only by the build but also by consumers of the
+artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+directory from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+directory is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those properties were removed
+or at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone, the Build-POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, e.g., `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
Review Comment:
no parentheses
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1932458087
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,477 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is the most widely used build tool in the Java world.
+Throughout the years, Maven has maintained backward compatibility, especially of its [POM file][2] with Model version
+4.0.0.
+
+The POM file fulfills two needs.
+First, the POM holds all the information and configuration, which are needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, for example dependencies, which are needed by projects which depend on the
+artifact.
+These dependent projects are called the "consumers".
+
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+Thus, any change in the POM's schema forces each participant of the ecosystem to either adopt the change or drop
+support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+In order for Maven to evolve, it's necessary to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## Required Java version
+
+Maven 4 requires Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 is only needed to **run Maven**!
+You can still compile against older Java versions using the same [compiler plugin configuration][6] as before.
+If you need to compile against or use another JDK, see the [Guide to Using Toolchains][7] (or the
+article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten Mulders).
+
+## POM Changes
+
+### Consumer POM
+
+Maven 4 generates a stripped down consumer POM that removes build information not needed by consumers, and deploys this
+to the remote repository.
+It does not deploy the `pom.xml` used to build the project.
+
+### Model version 4.1.0
+
+Maven 4 updates the POM version to 4.1.0 which defines the namespace `http://maven.apache.org/POM/4.1.0`.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the build POM, while the consumer POM will still use
+version 4.0.0.
+Maven generates the consumer POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 if you don't need to use the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project built with Maven.
+The [top level directory][32] of a Maven project contains at least the source folder `src` and the project's POM file
+`pom.xml`.
+A Maven project may have other Maven projects within subdirectories, each with its own `pom.xml` file.
+Each project within a subdirectory is called a "subproject".
+
+Example: Project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects unless they are linked from the root POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+Projects which have at least one subproject are called "multi-module projects", while those which do not have any
+subprojects are called "single module projects".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated `bom` packaging type to provide a [Bill of Materials BOM][4].
+This now differentiates between parent POMs and dependency-managing BOMs.
+The new type is only available as a build POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible consumer POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build.
+In other words: you should only import external BOMs.
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing build POM and consumer POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "consumer POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, for example plugin configuration!
+* Some of the build-related content which is (as of now) still available in the consumer POM might be available only in
+ the build POM in the future.
+
+| Content | Build POM | Consumer POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a consumer POM based on version 4.1.0, for example
+when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, for example a `maven.config` or
+`jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the build POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, for example when you want to define the path to a `checkstyle-suppressions.xml`
+file for the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+current working directory.
+The `rootDirectory` can only contain a value when either a `.mvn` directory is defined or the `root` attribute is set to
+true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4 those properties were removed or marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 consumer POM is set in stone, the build POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, like `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration.
+
+Example
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, for example `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects can cause confusion in Maven 3.
+When the build of subproject B, which requires subproject A, is failing for whatever reason, Maven 3 is telling
+the user to fix the error and then resume the build with `--resume-from :<nameOfTheFailingSubproject>`.
+But doing this instantly fails the build again, because the required subproject A couldn't be found (as it was not
+rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (for example Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where successfully
+built subprojects were deployed to the (local or remote) repository, but failed subprojects were not.
+This was finally changed in Maven 4 to what most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+in Maven 3, for example using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, always define fixed versions of all the plugins you use.
+By doing this, you are in control of your build.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM.
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which breaks the build when the severity of at least one log
+message matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, for example, `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break.
+Instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+In Maven 3 the lifecycle is an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more fine-grained execution of dependent phases.
+For example, the `compile` phase must execute after `compile-only` project dependencies have reached the `ready` phase.
+Maven 4 also allows to skip phases (in comparison to the old graph).
+For example, it's possible to `deploy` an artifact without `install`ing it to the user repository.
+
+For compatibility, the execution behavior is not really changed by default compared to Maven 3.
+In order to actually leverage the new tree-based lifecycle, the user has to enable the concurrent builder using
+`-b concurrent`.
+Running with the concurrent builder will allow finer grained dependency instead of the usual Maven 3 per-project
+dependency.
+With the usual builders and run `mvn verify`, a project will run up to the verify phase, before a dependent project can
+start being built, whereas the concurrent builder will allow a dependant project to be built as soon as the dependencies
+are at the `ready` phase.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before:` and an `after:` phase, allowing plugins to bind themselves to those.
+For example, if you want to set up test data before running your integration tests, you could execute tasks during the
+`before:integration-test` phase.
+
+If this is not enough, perhaps because you want to do multiple things inside the same phase, you can order each
+execution inside a phase by using square brackets with an integer at the end of the phase name.
+
+Example
+
+```
+before:integration-test[100]
+before:integration-test[200]
+```
+
+**Warning**: The conceptual `pre-*` and `post-*` phases, which were only available for selected phases and had
+inconsistent naming, are deprecated.
+Don't use them!
+This becomes even more important if you are binding a plugin to the `post-*` phase of a lifecycle phase because the
+`pre-*` phase of the phase you really want to bind to does not exist, for example, binding to `process-resources` phase
+because there was no `pre-compile` phase.
+
+## Maven plugins, security, and tools
+
+### Maven plugins
+
+As mentioned above, Maven 4 contains significant code and API updates, resulting in breaking changes for (very) old
+Maven plugins that have not been updated to use the recommended APIs.
+Major changes regarding plugins include a proper immutable plugin model together with a revised plugin API.
+The updated API provides hints as preparation for Maven 4.
+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.
+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.
+
+**Advice**: If you are maintaining a Maven plugin, you should test it with Maven 3.9.x.
+Pay close attention to upcoming warnings and update the plugin accordingly.
+
+### Improved encryption
+
+Security is important, and storing unencrypted passwords is bad practice.
+Maven 3's password encryption had several serious issues and could more accurately be called "password obfuscation".
+Maven 4 instead has a completely redone encryption system, based on Maven Encryption (`mvnenc`) - a standalone CLI tool.
Review Comment:
> But
>
> > based on Maven Encryption (`mvnenc`) - a standalone CLI tool.
>
> feels wrong to me. I would rather remove the sentence then altogether.
The phrasing is based on @cstamas blog about it:
> Maven4 password encryption is handled by the new CLI tool: mvnenc.
Shall I add a link to https://maven.apache.org/guides/mini/guide-encryption.html here, because that's the guide about encryption, which can (or should) hold the details.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1941795223
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,476 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is the most widely used build tool in the Java world.
+Throughout the years, Maven has maintained backward compatibility, especially of its [POM file][2] with Model version
+4.0.0.
+
+The POM file fulfills two needs.
+First, the POM holds all the information and configuration, which are needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, for example dependencies, which are needed by projects which depend on the
+artifact.
+These dependent projects are called the "consumers".
+
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+Thus, any change in the POM's schema forces each participant of the ecosystem to either adopt the change or drop
+support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+In order for Maven to evolve, it's necessary to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## Required Java version
+
+Maven 4 requires Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements.
+
+**Important note**: Java 17 is only needed to **run Maven**!
+You can still compile against older Java versions using the same [compiler plugin configuration][6] as before.
+If you need to compile against or use another JDK, see the [Guide to Using Toolchains][7] (or the
+article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten Mulders).
+
+## POM Changes
+
+### Consumer POM
+
+Maven 4 generates a stripped down consumer POM that removes build information not needed by consumers, and deploys this
+to the remote repository.
+It does not deploy the `pom.xml` used to build the project.
+
+### Model version 4.1.0
+
+Maven 4 updates the POM version to 4.1.0 which defines the namespace `http://maven.apache.org/POM/4.1.0`.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the build POM, while the consumer POM will still use
+version 4.0.0.
+Maven generates the consumer POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 if you don't need to use the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project built with Maven.
+The [top level directory][32] of a Maven project contains at least the source folder `src` and the project's POM file
+`pom.xml`.
+A Maven project may have other Maven projects within subdirectories, each with its own `pom.xml` file.
+Each project within a subdirectory is called a "subproject".
+
+Example: Project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects unless they are linked from the root POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+Projects which have at least one subproject are called "multi-module projects", while those which do not have any
+subprojects are called "single module projects".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated `bom` packaging type to provide a [Bill of Materials BOM][4].
+This now differentiates between parent POMs and dependency-managing BOMs.
+The new type is only available as a build POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible consumer POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build.
+In other words: you should only import external BOMs.
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing build POM and consumer POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "consumer POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, for example plugin configuration!
+* Some of the build-related content which is (as of now) still available in the consumer POM might be available only in
+ the build POM in the future.
+
+| Content | Build POM | Consumer POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a consumer POM based on version 4.1.0, for example
+when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, for example a `maven.config` or
+`jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the build POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, for example when you want to define the path to a `checkstyle-suppressions.xml`
+file for the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+current working directory.
+The `rootDirectory` can only contain a value when either a `.mvn` directory is defined or the `root` attribute is set to
+true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4 those properties were removed or marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 consumer POM is set in stone, the build POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, like `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration.
+
+Example
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, for example `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects can cause confusion in Maven 3.
+When the build of subproject B, which requires subproject A, is failing for whatever reason, Maven 3 is telling
+the user to fix the error and then resume the build with `--resume-from :<nameOfTheFailingSubproject>`.
+But doing this instantly fails the build again, because the required subproject A couldn't be found (as it was not
+rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (for example Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where successfully
Review Comment:
TLDR: I removed it, because nothing has changed.
Long story: I was assuming this too, because I was sure that I did hear it multiple times in a talk/chat that this would be the case. But the truth is, that the default value for `deployAtEnd` is still `false` in Maven 4 branch of the deploy plugin (same for install plugin). It "just" got several improvements, but even those slightly before the first maven 4 release, so also available in Maven 3 version of the plugin. Thanks for pointing this out!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "mthmulders (via GitHub)" <gi...@apache.org>.
mthmulders commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894580250
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's new in Maven 4?
+
+Maven is over 20 years old and is one of the most used build-tool in the Java world.
+Since all the years one important rule was the highest backward-compatibility as possible, especially with
+its [POM-schema with Model version 4.0.0][2], used for the build itself, but also by consumers.
+This made Maven more than a tool, but a whole ecosystem with a lot of things depended on the POM, esp. the Maven Central
+repository, other build tools and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare to changes which are impossible nowadays, like a complete new build schema.
+
+Another pain point of Maven 3 is a code base with a lot of deprecated, convoluted, non performant and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebases contains old Java code that can be optimized nowadays, but also old
+dependencies and bad API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM-Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction the Model version 4.0.0 is used not only for the build, but also by consumers of the
+artifact.
+But several contents of the POM are only necessary for the build while others like the dependencies are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As names suggest the "Build-POM" will contain all information needed for to build the artifact, e.g. used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep those which are really needed to use the artifact, e.g. dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4 a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others got marked as deprecated.
+To not break the ecosystem this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as like every software update - it's suggested to update them to 4.1.0, e.g. to avoid problems when deprecated
+things get removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 till today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files the wording "Maven project" is used.
+However, project containing multiple parts, e.g. an API and a client, each of those parts was called "module" and listed
+in the `<modules>` section of the POM, leading to the terms of "multi-module project".
+This wording introduced some inconsistency, especially as projects with any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9 the term "module" raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>`analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency managing BOMs.
+While the new type is only available with model Version 4.1.0 the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2004][5].
+
+**Note**: With Maven 4 it's also possible to exclude dependencies which are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven4 importing BOMs with classifier is now possible.
+Therefore, Maven team suggests that projects BOMs be generated as classified artifacts (see Maven build "skinny" vs "
Review Comment:
The clarification helps me a lot, thanks @Bukama and @cstamas!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894577113
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -325,11 +329,11 @@ See [MNG-8286][27] for more information about supported functions.
#### Lifecycle changed from graph to tree
-Up to Maven 3, the lifecycle was a mathematical graph.
+Up to Maven 3 the lifecycle was a literally an ordered list which contains all phases.
Review Comment:
Thanks again!
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -381,15 +385,17 @@ article ["Handling sensitive data in Maven"][31] by Maven maintainer Tamás Cser
### Maven Resolver
The [Maven Artifact Resolver][28] is a library for working with artifact repositories and dependency resolution.
-Maven 4 will include the new 2.0 release of this library, which contains more than 150 fixes, upgrades, and improvements,
-e.g., a Java native HTTP-Client - thanks to raising the Java version requirement to JDK 17!
+Maven 4 will include the new 2.0 release of this library, which contains more than 150 fixes, upgrades, and
+improvements, e.g., a Java native HTTP-Client - thanks to raising the Java version requirement to JDK 17!
+Another big difference in comparison with Maven 3 is that with the new major version the resolver aims to be hidden
+behind the new Maven API and thus not used directly anymore.
Review Comment:
Thanks again!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "cstamas (via GitHub)" <gi...@apache.org>.
cstamas commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1895742123
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicate code
+which costs the volunteers who maintain Maven a lot of time.
+This means that the Maven codebase contains not only old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only by the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements because you need to compile against or use another JDK, please look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was held in March 2024, shortly before Java 22 was
+released. One reason Java 17 was chosen over Java 21 was that it was (at this time) the second-last Java version for
+which many vendors offer long-term support.*
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates and even removals.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only the use of newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, you should always define fixed versions of all the plugins you use!
+By doing this, you are in control of your build - at the cost of being responsible for upgrading the versions yourself.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM!
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which will break the build when at least one log message
+matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, e.g., `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break; instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3, the lifecycle was an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more consistent execution of dependent phases, e.g., `compile` must execute after `compile-only` project
+dependencies have reached the `ready` phase, and also allows "skipping" phases (in comparison to the old graph), e.g.,
+`deploy` an artifact without `install`ing it to the user repository.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before` and `after` phase, allowing plugins to bind themselves to those by adding their
+prefixes to the name of the main phase.
+For example, if you want to set up test data before running your integration tests, you could execute tasks during the
+`before-integration-test` phase.
+
+If this is not enough, perhaps because you want to do multiple things inside the same phase, you can order each
+execution inside a phase by using square brackets with an integer at the end of the phase name, e.g.,
+
+```
+before-integration-test[100]
+before-integration-test[200]
+```
+
+**Warning**: The conceptual `pre-*` and `post-*` phases, which were only available for selected phases and had
+inconsistent naming, are deprecated - don't use them!
+This becomes even more important if you were binding a plugin to the `post-*` phase of a lifecycle phase because the
+`pre-*` phase of the phase you really wanted to bind to did not exist, e.g., binding to `process-resources` phase
+because there was no `pre-compile` phase.
+
+## Maven plugins, security and tools
+
+### Maven plugins
+
+As mentioned above, Maven 4 contains significant code and API updates, resulting in breaking changes for (very) old
+Maven plugins that were not updated to use the recommended APIs.
+Major changes regarding plugins include a proper immutable plugin model together with a revised plugin API.
+The updated API provides hints as preparation for Maven 4.
+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.
+If a plugin still relies on long-deprecated and now removed Plexus dependency resolution, it will no longer work.
Review Comment:
```suggestion
If a plugin still relies on long-deprecated and now removed Plexus dependency injection, it will no longer work.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "cstamas (via GitHub)" <gi...@apache.org>.
cstamas commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894125583
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's new in Maven 4?
+
+Maven is over 20 years old and is one of the most used build-tool in the Java world.
+Since all the years one important rule was the highest backward-compatibility as possible, especially with
+its [POM-schema with Model version 4.0.0][2], used for the build itself, but also by consumers.
+This made Maven more than a tool, but a whole ecosystem with a lot of things depended on the POM, esp. the Maven Central
+repository, other build tools and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare to changes which are impossible nowadays, like a complete new build schema.
+
+Another pain point of Maven 3 is a code base with a lot of deprecated, convoluted, non performant and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebases contains old Java code that can be optimized nowadays, but also old
+dependencies and bad API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM-Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction the Model version 4.0.0 is used not only for the build, but also by consumers of the
+artifact.
+But several contents of the POM are only necessary for the build while others like the dependencies are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As names suggest the "Build-POM" will contain all information needed for to build the artifact, e.g. used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep those which are really needed to use the artifact, e.g. dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4 a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others got marked as deprecated.
+To not break the ecosystem this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as like every software update - it's suggested to update them to 4.1.0, e.g. to avoid problems when deprecated
+things get removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 till today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files the wording "Maven project" is used.
+However, project containing multiple parts, e.g. an API and a client, each of those parts was called "module" and listed
+in the `<modules>` section of the POM, leading to the terms of "multi-module project".
+This wording introduced some inconsistency, especially as projects with any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9 the term "module" raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>`analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency managing BOMs.
+While the new type is only available with model Version 4.1.0 the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2004][5].
+
+**Note**: With Maven 4 it's also possible to exclude dependencies which are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven4 importing BOMs with classifier is now possible.
+Therefore, Maven team suggests that projects BOMs be generated as classified artifacts (see Maven build "skinny" vs "
Review Comment:
So to recap:
* BOM import should happen only with POMs coming from outside of reactor (in other words "you should import only external BOMs").
* BOM creation does not matter, doing it by hand is fine as well, but generating BOMs is much more less error prone, as you "just do the usual maven stuff" and generator makes you a BOM out of it. Less typos, less room for mistakes. And, it does not becomes "tempting" to import it either :smile: Still, due to reason above, "not reusing it within reactor" means you need to manually maintain two times same information (once the versions in your build, and once in your manually crafted BOM), hence automating the BOM generation makes much more sense.
* The definition of BOM is not enforced, you can still author manually or generate whatever kind of BOM you want. We just offered this naming similar to shading (skinny vs fat).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "cstamas (via GitHub)" <gi...@apache.org>.
cstamas commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894125583
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's new in Maven 4?
+
+Maven is over 20 years old and is one of the most used build-tool in the Java world.
+Since all the years one important rule was the highest backward-compatibility as possible, especially with
+its [POM-schema with Model version 4.0.0][2], used for the build itself, but also by consumers.
+This made Maven more than a tool, but a whole ecosystem with a lot of things depended on the POM, esp. the Maven Central
+repository, other build tools and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare to changes which are impossible nowadays, like a complete new build schema.
+
+Another pain point of Maven 3 is a code base with a lot of deprecated, convoluted, non performant and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebases contains old Java code that can be optimized nowadays, but also old
+dependencies and bad API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM-Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction the Model version 4.0.0 is used not only for the build, but also by consumers of the
+artifact.
+But several contents of the POM are only necessary for the build while others like the dependencies are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As names suggest the "Build-POM" will contain all information needed for to build the artifact, e.g. used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep those which are really needed to use the artifact, e.g. dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4 a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others got marked as deprecated.
+To not break the ecosystem this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as like every software update - it's suggested to update them to 4.1.0, e.g. to avoid problems when deprecated
+things get removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 till today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files the wording "Maven project" is used.
+However, project containing multiple parts, e.g. an API and a client, each of those parts was called "module" and listed
+in the `<modules>` section of the POM, leading to the terms of "multi-module project".
+This wording introduced some inconsistency, especially as projects with any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9 the term "module" raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>`analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency managing BOMs.
+While the new type is only available with model Version 4.1.0 the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2004][5].
+
+**Note**: With Maven 4 it's also possible to exclude dependencies which are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven4 importing BOMs with classifier is now possible.
+Therefore, Maven team suggests that projects BOMs be generated as classified artifacts (see Maven build "skinny" vs "
Review Comment:
So to recap:
* BOM import should happen only with POMs not coming from reactor (in other words "you should import only external BOMs").
* BOM creation does not matter, doing it by hand is fine as well, but generating BOMs is much more less error prone, as you "just do the usual maven stuff" and generator makes you a BOM out of it. Less typos, less room for mistakes. And, it does not becomes "tempting" to import it either :smile:
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "elharo (via GitHub)" <gi...@apache.org>.
elharo commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1895844594
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
Review Comment:
TBH, that's not totally true. It could have been stable and much more flexible than it is. The original Maven designers made some common mistakes in XML that locked POMs down far more than they had to be. It could have been stable and flexible. Maven 4 does not seem to have improved in this regard.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicate code
+which costs the volunteers who maintain Maven a lot of time.
Review Comment:
volunteers --> developers
Not everyone is a volunteer, at least not all the time.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicate code
Review Comment:
Please avoid the word "performant". It's ugly jargon. If you mean slow, say slow.
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicate code
+which costs the volunteers who maintain Maven a lot of time.
+This means that the Maven codebase contains not only old Java code that can be optimized nowadays but also old
Review Comment:
I'm not aware of any code in Maven that can be optimized now that couldn't be optimized in Java 7 and earlier.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "gnodet (via GitHub)" <gi...@apache.org>.
gnodet commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894472402
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -381,15 +385,17 @@ article ["Handling sensitive data in Maven"][31] by Maven maintainer Tamás Cser
### Maven Resolver
The [Maven Artifact Resolver][28] is a library for working with artifact repositories and dependency resolution.
-Maven 4 will include the new 2.0 release of this library, which contains more than 150 fixes, upgrades, and improvements,
-e.g., a Java native HTTP-Client - thanks to raising the Java version requirement to JDK 17!
+Maven 4 will include the new 2.0 release of this library, which contains more than 150 fixes, upgrades, and
+improvements, e.g., a Java native HTTP-Client - thanks to raising the Java version requirement to JDK 17!
+Another big difference in comparison with Maven 3 is that with the new major version the resolver aims to be hidden
+behind the new Maven API and thus not used directly anymore.
Review Comment:
`Another major difference compared to Maven 3 is that in the new major version, the resolver is hidden behind the new Maven API and is no longer used directly by plugins.`
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "cstamas (via GitHub)" <gi...@apache.org>.
cstamas commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894104074
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's new in Maven 4?
+
+Maven is over 20 years old and is one of the most used build-tool in the Java world.
+Since all the years one important rule was the highest backward-compatibility as possible, especially with
+its [POM-schema with Model version 4.0.0][2], used for the build itself, but also by consumers.
+This made Maven more than a tool, but a whole ecosystem with a lot of things depended on the POM, esp. the Maven Central
+repository, other build tools and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare to changes which are impossible nowadays, like a complete new build schema.
+
+Another pain point of Maven 3 is a code base with a lot of deprecated, convoluted, non performant and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebases contains old Java code that can be optimized nowadays, but also old
+dependencies and bad API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM-Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction the Model version 4.0.0 is used not only for the build, but also by consumers of the
+artifact.
+But several contents of the POM are only necessary for the build while others like the dependencies are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As names suggest the "Build-POM" will contain all information needed for to build the artifact, e.g. used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep those which are really needed to use the artifact, e.g. dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4 a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others got marked as deprecated.
+To not break the ecosystem this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as like every software update - it's suggested to update them to 4.1.0, e.g. to avoid problems when deprecated
+things get removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 till today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files the wording "Maven project" is used.
+However, project containing multiple parts, e.g. an API and a client, each of those parts was called "module" and listed
+in the `<modules>` section of the POM, leading to the terms of "multi-module project".
+This wording introduced some inconsistency, especially as projects with any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9 the term "module" raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>`analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency managing BOMs.
+While the new type is only available with model Version 4.1.0 the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2004][5].
+
+**Note**: With Maven 4 it's also possible to exclude dependencies which are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven4 importing BOMs with classifier is now possible.
+Therefore, Maven team suggests that projects BOMs be generated as classified artifacts (see Maven build "skinny" vs "
Review Comment:
Our stance (@gnodet could chime in when online) is following: BOMs should be _generated_ and not used within reactor (see issues), because users are "tempted" to create BOMs within reactor (is fine, as long BOM is "published only"), and then reuse BOM in same way as any external BOM would be reused: by importing within reactor. But, importing within reactor causes "build peculiarities" usually unexpected to users. Hence, we think that _generating BOMs_ simply prevents the two issues, as reactor dependendencies should be managed using inheritance, as it was always the case with Maven. Appearance of BOMs simply caused this "boost of creativity", to reuse them within reactor, but also publish them to downstream users, and it is wrong. Hence, Maven 4 shows an "example", and generates it's own BOMs. Related https://issues.apache.org/jira/browse/MNG-8012 and https://issues.apache.org/jira/browse/MNG-8009
In short: only external BOMs should be imported to reactor.
As per "what is a BOM", there is a split among us as can be seen in this old PR: https://github.com/apache/maven/pull/689
For some, "[BOM represents only the set of modules of a multimodule](https://github.com/apache/maven/pull/689#issuecomment-1061640064)" (only the reactor, so to say) while for others (@gnodet and me included) "BOM is bill of materials", so full stack (if I do an extension for Maven version X, I want same version of resolver, logging, Sisu etc as well... Similarly, look at all our plugins: after version property defining Maven version that plugins builds against, property is usually followed by a section with bunch of "keep in lockstep with Maven" version properties for logging, resolver, etc). Hence, the "skinny" (first definition) vs "fat" (second definition). In fact, Maven4 generates both now, so pleases both parties.
Of course, Maven 4 build generated BOMs can be used only in Maven 4 builds, as only Maven 4 allows importing BOMs with classifiers... So for Maven3, this is still an issue.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on PR #598:
URL: https://github.com/apache/maven-site/pull/598#issuecomment-2557755332
Thanks for the feedback and the editing @gnodet!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "elharo (via GitHub)" <gi...@apache.org>.
elharo commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1898740783
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, and duplicate code
+which costs the developers who maintain Maven a lot of time.
+This means that the Maven codebase contains not only old Java code but also old dependencies and poor API design of its
+own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only by the build but also by consumers of the
+artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs) or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
Review Comment:
folder --> directory
related to or is?
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, and duplicate code
+which costs the developers who maintain Maven a lot of time.
+This means that the Maven codebase contains not only old Java code but also old dependencies and poor API design of its
+own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only by the build but also by consumers of the
+artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs) or it may break your build (as
Review Comment:
delete " or it may break your build (as shown in [MNG-8009][32])"
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, and duplicate code
+which costs the developers who maintain Maven a lot of time.
+This means that the Maven codebase contains not only old Java code but also old dependencies and poor API design of its
+own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only by the build but also by consumers of the
+artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
Review Comment:
Try to be more precise. "final outcome" is unclear. Perhaps what's meant is something like "The build pom is only available in Model version 4.1 and later but the consumer pom is..."
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1898723012
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements because you need to compile against or use another JDK, please look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was held in March 2024, shortly before Java 22 was
Review Comment:
> delete this note; it's not important
Hm okay. I wanted to inform, why not Java 21.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1898715658
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
Review Comment:
I depends :D
Some of the properties mentioned in the PR are now deprecated and some are now also "hidden"(but it's not written what "hidden" means). Others are gone as they were renamed, e.g. `executionRootDir` got renamed to `topdir`. So depending on which variables a "hacker" is using nowadays, it will or won't work in the future. I think we can't write a more specific information / warning here.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1927449490
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,477 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is the most widely used build tool in the Java world.
+Throughout the years, Maven has maintained backward compatibility, especially of its [POM file][2] with Model version
+4.0.0.
+
+The POM file fulfills two needs.
+First, the POM holds all the information and configuration, which are needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, for example dependencies, which are needed by projects which depend on the
+artifact.
+These dependent projects are called the "consumers".
+
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+Thus, any change in the POM's schema forces each participant of the ecosystem to either adopt the change or drop
+support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+In order for Maven to evolve, it's necessary to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## Required Java version
+
+Maven 4 requires Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 is only needed to **run Maven**!
+You can still compile against older Java versions using the same [compiler plugin configuration][6] as before.
+If you need to compile against or use another JDK, see the [Guide to Using Toolchains][7] (or the
+article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten Mulders).
+
+## POM Changes
+
+### Consumer POM
+
+Maven 4 generates a stripped down consumer POM that removes build information not needed by consumers, and deploys this
+to the remote repository.
+It does not deploy the `pom.xml` used to build the project.
+
+### Model version 4.1.0
+
+Maven 4 updates the POM version to 4.1.0.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the build POM, while the consumer POM will still use
+version 4.0.0.
+Maven generates the consumer POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 if you don't need to use the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project built with Maven.
+The [top level directory][32] of a Maven project contains at least the source folder `src` and the project's POM file
+`pom.xml`.
+A Maven project may have other Maven projects within subdirectories, each with its own `pom.xml` file.
+Each project within a subdirectory is called a "subproject".
+
+Example: Project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects unless they are linked from the root POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+Projects which have at least one subproject are called "multi-module projects", while those which do not have any
+subprojects are called "single module projects".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated `bom` packaging type to provide a [Bill of Materials BOM][4].
+This now differentiates between parent POMs and dependency-managing BOMs.
+The new type is only available as a build POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible consumer POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build.
+In other words: you should only import external BOMs.
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing build POM and consumer POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "consumer POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, for example plugin configuration!
+* Some of the build-related content which is (as of now) still available in the consumer POM might be available only in
+ the build POM in the future.
+
+| Content | Build POM | Consumer POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a consumer POM based on version 4.1.0, for example
+when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, for example a `maven.config` or
+`jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the build POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, for example when you want to define the path to a `checkstyle-suppressions.xml`
+file for the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+current working directory.
+The `rootDirectory` can only contain a value when either a `.mvn` directory is defined or the `root` attribute is set to
+true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4 those properties were removed or marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 consumer POM is set in stone, the build POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, like `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration.
+
+Example
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, for example `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects can cause confusion in Maven 3.
+When the build of subproject B, which requires subproject A, is failing for whatever reason, Maven 3 is telling
+the user to fix the error and then resume the build with `--resume-from :<nameOfTheFailingSubproject>`.
+But doing this instantly fails the build again, because the required subproject A couldn't be found (as it was not
+rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (for example Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where successfully
+built subprojects were deployed to the (local or remote) repository, but failed subprojects were not.
+This was finally changed in Maven 4 to what most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+in Maven 3, for example using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, always define fixed versions of all the plugins you use.
+By doing this, you are in control of your build.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM.
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which breaks the build when the severity of at least one log
+message matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, for example, `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break.
+Instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+In Maven 3 the lifecycle is an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more fine-grained execution of dependent phases.
+For example, the `compile` phase must execute after `compile-only` project dependencies have reached the `ready` phase.
+Maven 4 also allows to skip phases (in comparison to the old graph).
+For example, it's possible to `deploy` an artifact without `install`ing it to the user repository.
+
+For compatibility, the execution behavior is not really changed by default compared to Maven 3.
+In order to actually leverage the new tree-based lifecycle, the user has to enable the concurrent builder using
+`-b concurrent`.
+Running with the concurrent builder will allow finer grained dependency instead of the usual Maven 3 per-project
+dependency.
+With the usual builders and run `mvn verify`, a project will run up to the verify phase, before a dependent project can
+start being built, whereas the concurrent builder will allow a dependant project to be built as soon as the dependencies
+are at the `ready` phase.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before:` and an `after:` phase, allowing plugins to bind themselves to those.
+For example, if you want to set up test data before running your integration tests, you could execute tasks during the
+`before:integration-test` phase.
+
+If this is not enough, perhaps because you want to do multiple things inside the same phase, you can order each
+execution inside a phase by using square brackets with an integer at the end of the phase name.
+
+Example
+
+```
+before:integration-test[100]
+before:integration-test[200]
+```
+
+**Warning**: The conceptual `pre-*` and `post-*` phases, which were only available for selected phases and had
+inconsistent naming, are deprecated.
+Don't use them!
+This becomes even more important if you are binding a plugin to the `post-*` phase of a lifecycle phase because the
+`pre-*` phase of the phase you really want to bind to does not exist, for example, binding to `process-resources` phase
+because there was no `pre-compile` phase.
+
+## Maven plugins, security, and tools
+
+### Maven plugins
+
+As mentioned above, Maven 4 contains significant code and API updates, resulting in breaking changes for (very) old
+Maven plugins that have not been updated to use the recommended APIs.
+Major changes regarding plugins include a proper immutable plugin model together with a revised plugin API.
+The updated API provides hints as preparation for Maven 4.
+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.
+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.
+
+**Advice**: If you are maintaining a Maven plugin, you should test it with Maven 3.9.x.
+Pay close attention to upcoming warnings and update the plugin accordingly.
+
+### Improved encryption
+
+Security is important, and storing unencrypted passwords is bad practice.
+Maven 3's password encryption had several serious issues and could more accurately be called "password obfuscation".
+Maven 4 instead has a completely redone encryption system, based on Maven Encryption (`mvnenc`) - a standalone CLI tool.
+As of now, it provides functionally equivalent operations as Maven 3 (see ["Maven: Password Encryption"][30]) but adds
+improvements like a `decrypt` functionality.
+A broad overview of the problems in Maven 3 and the solution in Maven 4 can be found in the
+article ["Handling sensitive data in Maven"][31] by Maven maintainer Tamás Cservenák.
+
+### Maven Resolver
+
+The [Maven Artifact Resolver][28] is a library for working with artifact repositories and dependency resolution.
+Maven 4 includes the new 2.0 release of this library, which contains more than 150 fixes, upgrades, and
+improvements, for example, a Java native HTTP-Client - thanks to raising the Java version requirement to JDK 17!
+Another major difference compared to Maven 3 is that in the new major version, the resolver is hidden behind the new
+Maven API and is no longer used directly by plugins.
Review Comment:
> This might be a good place to document the property `-Dmaven.resolver.dependencyManagerTransitivity=false`
>
> [MNG-8333 Document Maven4 transitive depMgt handling](https://issues.apache.org/jira/browse/MNG-8333)
I was thinking about this quite a time and started to change the text here, but in the end I don't want to add it, because this argument should be in a own Maven resolver guide, which also describes WHAT transitive dependency management is (including examples).
edit: Created a site issue:
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "kwin (via GitHub)" <gi...@apache.org>.
kwin commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1931964792
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,477 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is the most widely used build tool in the Java world.
+Throughout the years, Maven has maintained backward compatibility, especially of its [POM file][2] with Model version
+4.0.0.
+
+The POM file fulfills two needs.
+First, the POM holds all the information and configuration, which are needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, for example dependencies, which are needed by projects which depend on the
+artifact.
+These dependent projects are called the "consumers".
+
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+Thus, any change in the POM's schema forces each participant of the ecosystem to either adopt the change or drop
+support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+In order for Maven to evolve, it's necessary to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## Required Java version
+
+Maven 4 requires Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 is only needed to **run Maven**!
+You can still compile against older Java versions using the same [compiler plugin configuration][6] as before.
+If you need to compile against or use another JDK, see the [Guide to Using Toolchains][7] (or the
+article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten Mulders).
+
+## POM Changes
+
+### Consumer POM
+
+Maven 4 generates a stripped down consumer POM that removes build information not needed by consumers, and deploys this
+to the remote repository.
+It does not deploy the `pom.xml` used to build the project.
+
+### Model version 4.1.0
+
+Maven 4 updates the POM version to 4.1.0 which defines the namespace `http://maven.apache.org/POM/4.1.0`.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the build POM, while the consumer POM will still use
+version 4.0.0.
+Maven generates the consumer POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 if you don't need to use the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project built with Maven.
+The [top level directory][32] of a Maven project contains at least the source folder `src` and the project's POM file
+`pom.xml`.
+A Maven project may have other Maven projects within subdirectories, each with its own `pom.xml` file.
+Each project within a subdirectory is called a "subproject".
+
+Example: Project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects unless they are linked from the root POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+Projects which have at least one subproject are called "multi-module projects", while those which do not have any
+subprojects are called "single module projects".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated `bom` packaging type to provide a [Bill of Materials BOM][4].
+This now differentiates between parent POMs and dependency-managing BOMs.
+The new type is only available as a build POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible consumer POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build.
+In other words: you should only import external BOMs.
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing build POM and consumer POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "consumer POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, for example plugin configuration!
+* Some of the build-related content which is (as of now) still available in the consumer POM might be available only in
+ the build POM in the future.
+
+| Content | Build POM | Consumer POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a consumer POM based on version 4.1.0, for example
+when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, for example a `maven.config` or
+`jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the build POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, for example when you want to define the path to a `checkstyle-suppressions.xml`
+file for the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+current working directory.
+The `rootDirectory` can only contain a value when either a `.mvn` directory is defined or the `root` attribute is set to
+true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4 those properties were removed or marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 consumer POM is set in stone, the build POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, like `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration.
+
+Example
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, for example `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects can cause confusion in Maven 3.
+When the build of subproject B, which requires subproject A, is failing for whatever reason, Maven 3 is telling
+the user to fix the error and then resume the build with `--resume-from :<nameOfTheFailingSubproject>`.
+But doing this instantly fails the build again, because the required subproject A couldn't be found (as it was not
+rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (for example Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where successfully
+built subprojects were deployed to the (local or remote) repository, but failed subprojects were not.
+This was finally changed in Maven 4 to what most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+in Maven 3, for example using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, always define fixed versions of all the plugins you use.
+By doing this, you are in control of your build.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM.
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which breaks the build when the severity of at least one log
+message matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, for example, `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break.
+Instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+In Maven 3 the lifecycle is an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more fine-grained execution of dependent phases.
+For example, the `compile` phase must execute after `compile-only` project dependencies have reached the `ready` phase.
+Maven 4 also allows to skip phases (in comparison to the old graph).
+For example, it's possible to `deploy` an artifact without `install`ing it to the user repository.
+
+For compatibility, the execution behavior is not really changed by default compared to Maven 3.
+In order to actually leverage the new tree-based lifecycle, the user has to enable the concurrent builder using
+`-b concurrent`.
+Running with the concurrent builder will allow finer grained dependency instead of the usual Maven 3 per-project
+dependency.
+With the usual builders and run `mvn verify`, a project will run up to the verify phase, before a dependent project can
+start being built, whereas the concurrent builder will allow a dependant project to be built as soon as the dependencies
+are at the `ready` phase.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before:` and an `after:` phase, allowing plugins to bind themselves to those.
+For example, if you want to set up test data before running your integration tests, you could execute tasks during the
+`before:integration-test` phase.
+
+If this is not enough, perhaps because you want to do multiple things inside the same phase, you can order each
+execution inside a phase by using square brackets with an integer at the end of the phase name.
+
+Example
+
+```
+before:integration-test[100]
+before:integration-test[200]
+```
+
+**Warning**: The conceptual `pre-*` and `post-*` phases, which were only available for selected phases and had
+inconsistent naming, are deprecated.
+Don't use them!
+This becomes even more important if you are binding a plugin to the `post-*` phase of a lifecycle phase because the
+`pre-*` phase of the phase you really want to bind to does not exist, for example, binding to `process-resources` phase
+because there was no `pre-compile` phase.
+
+## Maven plugins, security, and tools
+
+### Maven plugins
+
+As mentioned above, Maven 4 contains significant code and API updates, resulting in breaking changes for (very) old
+Maven plugins that have not been updated to use the recommended APIs.
+Major changes regarding plugins include a proper immutable plugin model together with a revised plugin API.
+The updated API provides hints as preparation for Maven 4.
+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.
+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.
+
+**Advice**: If you are maintaining a Maven plugin, you should test it with Maven 3.9.x.
+Pay close attention to upcoming warnings and update the plugin accordingly.
+
+### Improved encryption
+
+Security is important, and storing unencrypted passwords is bad practice.
+Maven 3's password encryption had several serious issues and could more accurately be called "password obfuscation".
+Maven 4 instead has a completely redone encryption system, based on Maven Encryption (`mvnenc`) - a standalone CLI tool.
Review Comment:
But
> based on Maven Encryption (`mvnenc`) - a standalone CLI tool.
feels wrong to me. I would rather remove the sentence then altogether.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "kwin (via GitHub)" <gi...@apache.org>.
kwin commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1931931860
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,477 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is the most widely used build tool in the Java world.
+Throughout the years, Maven has maintained backward compatibility, especially of its [POM file][2] with Model version
+4.0.0.
+
+The POM file fulfills two needs.
+First, the POM holds all the information and configuration, which are needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, for example dependencies, which are needed by projects which depend on the
+artifact.
+These dependent projects are called the "consumers".
+
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+Thus, any change in the POM's schema forces each participant of the ecosystem to either adopt the change or drop
+support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+In order for Maven to evolve, it's necessary to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## Required Java version
+
+Maven 4 requires Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 is only needed to **run Maven**!
+You can still compile against older Java versions using the same [compiler plugin configuration][6] as before.
+If you need to compile against or use another JDK, see the [Guide to Using Toolchains][7] (or the
+article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten Mulders).
+
+## POM Changes
+
+### Consumer POM
+
+Maven 4 generates a stripped down consumer POM that removes build information not needed by consumers, and deploys this
+to the remote repository.
+It does not deploy the `pom.xml` used to build the project.
+
+### Model version 4.1.0
+
+Maven 4 updates the POM version to 4.1.0 which defines the namespace `http://maven.apache.org/POM/4.1.0`.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the build POM, while the consumer POM will still use
+version 4.0.0.
+Maven generates the consumer POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 if you don't need to use the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project built with Maven.
+The [top level directory][32] of a Maven project contains at least the source folder `src` and the project's POM file
+`pom.xml`.
+A Maven project may have other Maven projects within subdirectories, each with its own `pom.xml` file.
+Each project within a subdirectory is called a "subproject".
+
+Example: Project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects unless they are linked from the root POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+Projects which have at least one subproject are called "multi-module projects", while those which do not have any
+subprojects are called "single module projects".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated `bom` packaging type to provide a [Bill of Materials BOM][4].
+This now differentiates between parent POMs and dependency-managing BOMs.
+The new type is only available as a build POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible consumer POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build.
+In other words: you should only import external BOMs.
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing build POM and consumer POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "consumer POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, for example plugin configuration!
+* Some of the build-related content which is (as of now) still available in the consumer POM might be available only in
+ the build POM in the future.
+
+| Content | Build POM | Consumer POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a consumer POM based on version 4.1.0, for example
+when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, for example a `maven.config` or
+`jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the build POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, for example when you want to define the path to a `checkstyle-suppressions.xml`
+file for the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+current working directory.
+The `rootDirectory` can only contain a value when either a `.mvn` directory is defined or the `root` attribute is set to
+true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4 those properties were removed or marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 consumer POM is set in stone, the build POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, like `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration.
+
+Example
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, for example `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects can cause confusion in Maven 3.
+When the build of subproject B, which requires subproject A, is failing for whatever reason, Maven 3 is telling
+the user to fix the error and then resume the build with `--resume-from :<nameOfTheFailingSubproject>`.
+But doing this instantly fails the build again, because the required subproject A couldn't be found (as it was not
+rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (for example Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where successfully
+built subprojects were deployed to the (local or remote) repository, but failed subprojects were not.
+This was finally changed in Maven 4 to what most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+in Maven 3, for example using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, always define fixed versions of all the plugins you use.
+By doing this, you are in control of your build.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM.
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which breaks the build when the severity of at least one log
+message matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, for example, `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break.
+Instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+In Maven 3 the lifecycle is an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more fine-grained execution of dependent phases.
+For example, the `compile` phase must execute after `compile-only` project dependencies have reached the `ready` phase.
+Maven 4 also allows to skip phases (in comparison to the old graph).
+For example, it's possible to `deploy` an artifact without `install`ing it to the user repository.
+
+For compatibility, the execution behavior is not really changed by default compared to Maven 3.
+In order to actually leverage the new tree-based lifecycle, the user has to enable the concurrent builder using
+`-b concurrent`.
+Running with the concurrent builder will allow finer grained dependency instead of the usual Maven 3 per-project
+dependency.
+With the usual builders and run `mvn verify`, a project will run up to the verify phase, before a dependent project can
+start being built, whereas the concurrent builder will allow a dependant project to be built as soon as the dependencies
+are at the `ready` phase.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before:` and an `after:` phase, allowing plugins to bind themselves to those.
+For example, if you want to set up test data before running your integration tests, you could execute tasks during the
+`before:integration-test` phase.
+
+If this is not enough, perhaps because you want to do multiple things inside the same phase, you can order each
+execution inside a phase by using square brackets with an integer at the end of the phase name.
+
+Example
+
+```
+before:integration-test[100]
+before:integration-test[200]
+```
+
+**Warning**: The conceptual `pre-*` and `post-*` phases, which were only available for selected phases and had
+inconsistent naming, are deprecated.
+Don't use them!
+This becomes even more important if you are binding a plugin to the `post-*` phase of a lifecycle phase because the
+`pre-*` phase of the phase you really want to bind to does not exist, for example, binding to `process-resources` phase
+because there was no `pre-compile` phase.
+
+## Maven plugins, security, and tools
+
+### Maven plugins
+
+As mentioned above, Maven 4 contains significant code and API updates, resulting in breaking changes for (very) old
+Maven plugins that have not been updated to use the recommended APIs.
+Major changes regarding plugins include a proper immutable plugin model together with a revised plugin API.
+The updated API provides hints as preparation for Maven 4.
+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.
+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.
+
+**Advice**: If you are maintaining a Maven plugin, you should test it with Maven 3.9.x.
+Pay close attention to upcoming warnings and update the plugin accordingly.
+
+### Improved encryption
+
+Security is important, and storing unencrypted passwords is bad practice.
+Maven 3's password encryption had several serious issues and could more accurately be called "password obfuscation".
+Maven 4 instead has a completely redone encryption system, based on Maven Encryption (`mvnenc`) - a standalone CLI tool.
Review Comment:
mvnenc is just a frontend, the underlying backend is rather https://github.com/codehaus-plexus/plexus-sec-dispatcher. Compare with #654.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1927468031
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,473 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of
+its [POM file][2] with Model version 4.0.0.
+
+The POM file fulfills two elementary needs.
+First, the POM holds all the information and configuration, which are only needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the
+artifact.
+These dependent projects are called the "consumers" (of an artifact).
+
+This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+This results in the situation that any change in the POM's schema forces each participant of the ecosystem to either
+adopt the change or drop support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+But Maven should be able to advance.
+For this, one important thing that's needed is to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+Maven 3 uses Model version 4.0.0 not only by the build but also by consumers of the artifact.
+However, several parts of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumers.
+Maven 4 therefore differentiates between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" contains all information needed to build the artifact, e.g., applied plugins
+and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is
+necessary to use an artifact as a dependency.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+Maven 4 introduces a new POM version 4.1.0.
+With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+Maven generates the Consumer-POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project build with Maven.
+The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM
+file.
+A Maven project may have other Maven projects within subdirectories.
+Each project within a subdirectories is called "subproject".
+
+Example: A project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects as long as they are not linked as such in the POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+The inconsistent wording led to the situation that many people calling subprojects "modules".
+Projects which have at least one subproject are often called "multi-module project", while those which don't have any
+are "single-module project".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible Consumer-POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words: you should import only external BOMs).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, e.g. plugin configuration!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
Review Comment:
Created an issue to describe the terms in a separate PR.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1915418100
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
Review Comment:
> This all need a better explanation with examples.
Please lay out what you mean. Shall I write/show an example of a Maven project's folder? This is done the users guide (https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html). And I don't think we need to explain this to someone who's interesting in information about the changes between Maven 3 and 4.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1923982976
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,468 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is the most widely used build tool in the Java world.
+Throughout the years, Maven has maintained backward compatibility, especially of its [POM file][2] with Model version
+4.0.0.
+
+The POM file fulfills two needs.
+First, the POM holds all the information and configuration, which are needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, for example dependencies, which are needed by projects which depend on the
+artifact.
+These dependent projects are called the "consumers".
+
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+Thus, any change in the POM's schema forces each participant of the ecosystem to either adopt the change or drop
+support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+In order for Maven to evolve, it's necessary to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## Required Java version
+
+Maven 4 requires Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 is only needed to **run Maven**!
+You can still compile against older Java versions using the same [compiler plugin configuration][6] as before.
+If you need to compile against or use another JDK, see the [Guide to Using Toolchains][7] (or the
+article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten Mulders).
+
+## POM Changes
+
+### Consumer POM
+
+Maven 4 generates a stripped down consumer POM that removes build information not needed by consumers, and deploys this
+to the remote repository.
+It does not deploy the `pom.xml` used to build the project.
+
+### Model version 4.1.0
+
+Maven 4 updates the POM version to 4.1.0.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the build POM, while the consumer POM will still use
+version 4.0.0.
+Maven generates the consumer POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 if you don't need to use the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project built with Maven.
+The [top level directory][32] of a Maven project contains at least the source folder `src` and the project's POM file
+`pom.xml`.
+A Maven project may have other Maven projects within subdirectories, each with its own `pom.xml` file.
+Each project within a subdirectory is called a "subproject".
+
+Example: Project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects unless they are linked from the root POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+Projects which have at least one subproject are called "multi-module projects", while those which do not have any
+subprojects are called "single module projects".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated `bom` packaging type to provide a [Bill of Materials BOM][4].
+This now differentiates between parent POMs and dependency-managing BOMs.
+The new type is only available as a build POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible consumer POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build.
+In other words: you should only import external BOMs.
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing build POM and consumer POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "consumer POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, for example plugin configuration!
+* Some of the build-related content which is (as of now) still available in the consumer POM might be available only in
+ the build POM in the future.
+
+| Content | Build POM | Consumer POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a consumer POM based on version 4.1.0, for example
+when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, for example a `maven.config` or
+`jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the build POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, for example when you want to define the path to a `checkstyle-suppressions.xml`
+file for the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+current working directory.
+The `rootDirectory` can only contain a value when either a `.mvn` directory is defined or the `root` attribute is set to
+true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4 those properties were removed or marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 consumer POM is set in stone, the build POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, like `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration.
+
+Example
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, for example `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects can cause confusion in Maven 3.
+When the build of subproject B, which requires subproject A, is failing for whatever reason, Maven 3 is telling
+the user to fix the error and then resume the build with `--resume-from :<nameOfTheFailingSubproject>`.
+But doing this instantly fails the build again, because the required subproject A couldn't be found (as it was not
+rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (for example Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where successfully
+built subprojects were deployed to the (local or remote) repository, but failed subprojects were not.
+This was finally changed in Maven 4 to what most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+in Maven 3, for example using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, always define fixed versions of all the plugins you use.
+By doing this, you are in control of your build.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM.
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which breaks the build when the severity of at least one log
+message matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, for example, `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break.
+Instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+In Maven 3 the lifecycle is an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more consistent execution of dependent phases.
+For example, the `compile` phase must execute after `compile-only` project dependencies have reached the `ready` phase.
+Maven 4 also allows to skip phases (in comparison to the old graph).
+For example, it's possible to `deploy` an artifact without `install`ing it to the user repository.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before-` and an `after-` phase, allowing plugins to bind themselves to those.
Review Comment:
Haha stupid me was mixing the old with the new ones. Thanks for catching!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "cstamas (via GitHub)" <gi...@apache.org>.
cstamas commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894125583
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's new in Maven 4?
+
+Maven is over 20 years old and is one of the most used build-tool in the Java world.
+Since all the years one important rule was the highest backward-compatibility as possible, especially with
+its [POM-schema with Model version 4.0.0][2], used for the build itself, but also by consumers.
+This made Maven more than a tool, but a whole ecosystem with a lot of things depended on the POM, esp. the Maven Central
+repository, other build tools and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare to changes which are impossible nowadays, like a complete new build schema.
+
+Another pain point of Maven 3 is a code base with a lot of deprecated, convoluted, non performant and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebases contains old Java code that can be optimized nowadays, but also old
+dependencies and bad API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM-Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction the Model version 4.0.0 is used not only for the build, but also by consumers of the
+artifact.
+But several contents of the POM are only necessary for the build while others like the dependencies are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As names suggest the "Build-POM" will contain all information needed for to build the artifact, e.g. used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep those which are really needed to use the artifact, e.g. dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4 a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others got marked as deprecated.
+To not break the ecosystem this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as like every software update - it's suggested to update them to 4.1.0, e.g. to avoid problems when deprecated
+things get removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 till today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files the wording "Maven project" is used.
+However, project containing multiple parts, e.g. an API and a client, each of those parts was called "module" and listed
+in the `<modules>` section of the POM, leading to the terms of "multi-module project".
+This wording introduced some inconsistency, especially as projects with any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9 the term "module" raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>`analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency managing BOMs.
+While the new type is only available with model Version 4.1.0 the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2004][5].
+
+**Note**: With Maven 4 it's also possible to exclude dependencies which are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven4 importing BOMs with classifier is now possible.
+Therefore, Maven team suggests that projects BOMs be generated as classified artifacts (see Maven build "skinny" vs "
Review Comment:
So to recap:
* BOM import should happen only with POMs coming from outside of reactor (in other words "you should import only external BOMs").
* BOM creation does not matter, doing it by hand is fine as well, but generating BOMs is much more less error prone, as you "just do the usual maven stuff" and generator makes you a BOM out of it. Less typos, less room for mistakes. And, it does not becomes "tempting" to import it either :smile:
* The definition of BOM is not enforced, you can still author manually or generate whatever kind of BOM you want. We just offered this naming similar to shading (skinny vs fat).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "cstamas (via GitHub)" <gi...@apache.org>.
cstamas commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894125583
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's new in Maven 4?
+
+Maven is over 20 years old and is one of the most used build-tool in the Java world.
+Since all the years one important rule was the highest backward-compatibility as possible, especially with
+its [POM-schema with Model version 4.0.0][2], used for the build itself, but also by consumers.
+This made Maven more than a tool, but a whole ecosystem with a lot of things depended on the POM, esp. the Maven Central
+repository, other build tools and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare to changes which are impossible nowadays, like a complete new build schema.
+
+Another pain point of Maven 3 is a code base with a lot of deprecated, convoluted, non performant and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebases contains old Java code that can be optimized nowadays, but also old
+dependencies and bad API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM-Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction the Model version 4.0.0 is used not only for the build, but also by consumers of the
+artifact.
+But several contents of the POM are only necessary for the build while others like the dependencies are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As names suggest the "Build-POM" will contain all information needed for to build the artifact, e.g. used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep those which are really needed to use the artifact, e.g. dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4 a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others got marked as deprecated.
+To not break the ecosystem this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as like every software update - it's suggested to update them to 4.1.0, e.g. to avoid problems when deprecated
+things get removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 till today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files the wording "Maven project" is used.
+However, project containing multiple parts, e.g. an API and a client, each of those parts was called "module" and listed
+in the `<modules>` section of the POM, leading to the terms of "multi-module project".
+This wording introduced some inconsistency, especially as projects with any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9 the term "module" raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>`analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency managing BOMs.
+While the new type is only available with model Version 4.1.0 the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2004][5].
+
+**Note**: With Maven 4 it's also possible to exclude dependencies which are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven4 importing BOMs with classifier is now possible.
+Therefore, Maven team suggests that projects BOMs be generated as classified artifacts (see Maven build "skinny" vs "
Review Comment:
So to recap:
* BOM import should happen only with POMs not coming from reactor (in other words "you should import only external BOMs").
* BOM creation does not matter, doing it by hand is fine as well, but generating BOMs is much more less error prone, as you "just do the usual maven stuff" and generator makes you a BOM out of it. Less typos, less room for mistakes. And, it does not becomes "tempting" to import it either :smile:
* The definition of BOM is not enforced, you can still author manually or generate whatever kind of BOM you want. We just offered this naming similar to shading (skinny vs fat).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "gnodet (via GitHub)" <gi...@apache.org>.
gnodet commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894381265
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,459 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially with
+its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven Central
+repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module" and listed
+in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a fully Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use of
+the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for the
+checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should be
+able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config` file
+or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements because you need to compile against or use another JDK, please look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was held in March 2024, shortly before Java 22 was
+released. One reason Java 17 was chosen over Java 21 was that it was (at this time) the second-last Java version for which many
+vendors offer long-term support.*
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates and even removals.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only the use of newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even if
+you didn't purposely change anything.
+To avoid this situation, you should always define fixed versions of all the plugins you use!
+By doing this, you are in control of your build - at the cost of being responsible for upgrading the versions yourself.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM!
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which will break the build when at least one log message
+matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, e.g., `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break; instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3, the lifecycle was a mathematical graph.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more consistent execution of dependent phases, e.g., `compile` must execute after `compile-only` project
+dependencies have reached the `ready` phase, and also allows "skipping" phases (in comparison to the old graph), e.g., `deploy`
+an artifact without `install`ing it to the user repository.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before` and `after` phase, allowing plugins to bind themselves to those by adding their
+prefixes to the name of the main phase.
+For example, if you want to set up test data before running your integration tests, you could execute tasks during the
+`before-integration-test` phase.
+
+If this is not enough, perhaps because you want to do multiple things inside the same phase, you can order each execution
+inside a phase by using square brackets with an integer at the end of the phase name, e.g.,
+
+```
+before-integration-test[100]
+before-integration-test[200]
+```
+
+**Warning**: The conceptual `pre-*` and `post-*` phases, which were only available for selected phases and had inconsistent
+naming, are deprecated - don't use them (anymore)!
+This becomes even more important if you were binding a plugin to the `post-*` phase of a lifecycle phase because the
+`pre-*` phase of the phase you really wanted to bind to did not exist, e.g., binding to `process-resources` phase
+because there was no `pre-compile` phase.
+
+## Maven plugins, security and tools
+
+### Maven plugins
+
+As mentioned above, Maven 4 will contain significant code and API updates, resulting in breaking changes for (very) old Maven plugins that
+were not updated to use the recommended APIs.
+Major changes regarding plugins include a proper immutable plugin model together with a revised plugin API.
+The updated API provides hints as preparation for Maven 4.
+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.
+If a plugin still relies on long-deprecated and now removed Plexus dependency resolution, it will no longer work
+and needs to be updated to use JSR-330 - see [Maven & JSR-330][26] for further information.
+
+**Advice**: If you are maintaining a Maven plugin, you should test it with Maven 3.9.x, pay close attention to upcoming
+warnings, and update the plugin accordingly.
+
+### Improved encryption
+
+Security is important, and storing unencrypted passwords is bad practice.
+Maven 3's password encryption had several serious issues and could more accurately be called "password obfuscation".
+Maven 4 instead has a completely redone encryption system, based on Maven Encryption (`mvnenc`) - a standalone CLI tool.
+As of now, it provides functionally equivalent operations as Maven 3 (see ["Maven: Password Encryption"][30]) but adds
+improvements like a `decrypt` functionality.
+A broad overview of the problems in Maven 3 and the solution in Maven 4 can be found in the
+article ["Handling sensitive data in Maven"][31] by Maven maintainer Tamás Cservenák.
+
+### Maven Resolver
+
+The [Maven Artifact Resolver][28] is a library for working with artifact repositories and dependency resolution.
+Maven 4 will include the new 2.0 release of this library, which contains more than 150 fixes, upgrades, and improvements,
+e.g., a Java native HTTP-Client - thanks to raising the Java version requirement to JDK 17!
Review Comment:
I think we should mention that the resolver aims at being hidden behind the Maven 4 API and that it should not be used directly anymore.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "gnodet (via GitHub)" <gi...@apache.org>.
gnodet commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894379108
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,459 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially with
+its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven Central
+repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module" and listed
+in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a fully Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use of
+the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for the
+checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should be
+able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config` file
+or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements because you need to compile against or use another JDK, please look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was held in March 2024, shortly before Java 22 was
+released. One reason Java 17 was chosen over Java 21 was that it was (at this time) the second-last Java version for which many
+vendors offer long-term support.*
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates and even removals.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only the use of newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+already in Maven 3, e.g., using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even if
+you didn't purposely change anything.
+To avoid this situation, you should always define fixed versions of all the plugins you use!
+By doing this, you are in control of your build - at the cost of being responsible for upgrading the versions yourself.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM!
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which will break the build when at least one log message
+matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, e.g., `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break; instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3, the lifecycle was a mathematical graph.
Review Comment:
The lifefcycle was really more a list than a graph.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894085776
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's new in Maven 4?
+
+Maven is over 20 years old and is one of the most used build-tool in the Java world.
+Since all the years one important rule was the highest backward-compatibility as possible, especially with
+its [POM-schema with Model version 4.0.0][2], used for the build itself, but also by consumers.
+This made Maven more than a tool, but a whole ecosystem with a lot of things depended on the POM, esp. the Maven Central
+repository, other build tools and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare to changes which are impossible nowadays, like a complete new build schema.
+
+Another pain point of Maven 3 is a code base with a lot of deprecated, convoluted, non performant and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebases contains old Java code that can be optimized nowadays, but also old
+dependencies and bad API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM-Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction the Model version 4.0.0 is used not only for the build, but also by consumers of the
+artifact.
+But several contents of the POM are only necessary for the build while others like the dependencies are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As names suggest the "Build-POM" will contain all information needed for to build the artifact, e.g. used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep those which are really needed to use the artifact, e.g. dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4 a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others got marked as deprecated.
+To not break the ecosystem this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as like every software update - it's suggested to update them to 4.1.0, e.g. to avoid problems when deprecated
+things get removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 till today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files the wording "Maven project" is used.
+However, project containing multiple parts, e.g. an API and a client, each of those parts was called "module" and listed
+in the `<modules>` section of the POM, leading to the terms of "multi-module project".
+This wording introduced some inconsistency, especially as projects with any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9 the term "module" raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>`analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency managing BOMs.
+While the new type is only available with model Version 4.1.0 the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2004][5].
+
+**Note**: With Maven 4 it's also possible to exclude dependencies which are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven4 importing BOMs with classifier is now possible.
+Therefore, Maven team suggests that projects BOMs be generated as classified artifacts (see Maven build "skinny" vs "
+fat" BOM).
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison about which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply for artefacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations, where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g. when
+condition based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Everytime a Maven build is executed it has to determine the projects root so identify things like the parent project,
+directory information and so on.
+To "help" Maven finding the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project specific configuration to run Maven, e.g. a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4 there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds the boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false) the directory of this POM file is considered the root directory.
+
+Another pain point in relation of the root directly is that until Maven 4 there was no official variable to make use of
+the root folder in your POM files, e.g. when you want to define the path to a `checkstyle-suppressions.xml` file for the
+checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined it should always have the same value for a given project, whereas the value of the`topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subprojects' own base directory, which was and is still accessibly via the `${basedir}` property for the usage in POM
+files and will always have a value.
+
+**Note:** In the past some people "hacked" workarounds for the`rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4 those "hacks" will most probably not work anymore, because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing central repository, the Build-POM should be
+able to evolve.
+This includes allowing the use of alternate syntaxes, by having Maven 4 providing a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects which uses this features is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected it's no longer required to define the parent versions in each subproject, when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parents and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partly supported usage of CI-friendly variables, e.g. `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4 no additional plugin is needed anymore, but full build-in support is provided.
+You can now use variables as versions in your configuration, e.g.
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by a `maven.config` file
+or as a parameter, e.g. `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent from one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuild too).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due the long-stand
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended to not use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully build subprojects when the overall build failed, and will skip to rebuild
+those if you resume the build.
+With Maven 4 it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g. Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve the daily work with those.
+Thanks to [MNG-6754][14] all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3 each subproject was having a different one.
+This should make it easier to identify the archives which belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in the situation where some (successfully
+build) subprojects where deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users are expecting:
+Only deploy when all subprojects were build successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK, but also comes with a more secure runtime as Java 17 includes more security features earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements, because you need to compile against or using another JDK, please have a look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was hold in March 2024, shortly before Java 22 was
+released.
+One reason Java 17 was chosen over Java 21, because it was (at this time) the second last Java version for which many
+vendors offer long-term-support.*
+
+### Application maintenance
+
+As with every update, especially major ones, large application maintenance happens, containing huge code, API and
+dependency updates and even removals.
+For example the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates contain not only usages of newer Java language features, but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing things that either never should have worked or were only kept for backward-compatibility
+already in Maven 3, e.g. using `${pom.*}` expressions.
+Maven own Super POM was also upgrading, which declares new default versions of Maven's core plugins.
+
+**Note**: Due upgrading the default versions of Maven plugins, your build might behave different that before, even if
+you didn't purposely change anything.
+To avoid this situation you should always define fixed versions of all the plugins you use!
+By doing this you are in control of your build - at the costs of being responsible to upgrade the versions yourself.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM!
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which will break the build when at least one log message
+matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument of a log level severity, e.g. `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so the `?` argument was added to the profile parameter.
+When using this the build won't break, but an information will be printed twice (at the start and the end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more and flexible ways to activate profiles, by providing condition based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3 the lifecycle was mathematical graph.
+This changed with Maven 4 where the lifecycle is defined as a tree of phases.
+This allows a more consistent execution of dependent phases, e.g. `compile` must execute after `compile-only` project
+dependencies have reached the `ready` phase, but also "skipping" phases (in comparison to the old graph), e.g. `deploy`
+an artifact without `install`ing it to the user repository.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before` and `after` phase, allowing plugins to bind themselves to those by adding their
+prefixes to the name of the main phase name.
+For example, if you want to set up test data before running your integration test you could execute stuff during the
+`before-integration-test` phase.
+
+If this is not enough, maybe because you want to do multiple things inside the same phase, you can order each execution
+inside a phase by using square brackets with an Integer at the end of the phase name, e.g.
+
+```
+before-integration-test[100]
+before-integration-test[200]
+```
+
+**Warning**: The conceptional `pre-*` and `post-*` phases, wich were only available to selected phases and homogeneously
+named are deprecated - don't use them (anymore)!
+This becomes even more important when you were binding a plugin to the `post-*` phase of a lifecycle phase, because the
+`pre-*` phase of the phase you really would like to bind to did not exist, e.g. binding to `process-resources` phase,
+because there was no `pre-compile`one.
+
+## Maven plugins, security and tools
+
+### Maven plugins
+
+As written above Maven 4 will contain huge code and API updates, resulting in breaking (very) old Maven plugins, which
+were not updated to the recommended APIs.
+Major changes regarding plugins contain a now proper immutable plugin model together with a changed plugin API.
+The updated API provides hints as a preparation for Maven 4.
+You can enable them passing the following argument to your build: `-Dmaven.plugin.validation=verbose`.
+You should also only rely on the official Maven BOMs when developing plugins.
+If a plugin still relies on long time deprecated and now removed Plexus dependency resolution, it will no longer work
+and needs to be updated to JSR-330 - see [Maven & JSR-330][26] for further information.
+
+**Advice**: If you are maintaining a Maven plugin, you should test it with Maven 3.9.x, have a close look at upcoming
+warnings and update the plugin.
+
+### Improved encryption
+
+Security is important and storing unencrypted passwords is bad.
+Maven 3's password encryption has several serious issues and could rather be call a “password obfuscation”.
+Maven 4 instead got a fully redone encryption, based on Maven Encryption (`mvnenc`) - a standalone CLI tool.
+As for now it provides functionally equivalent operations as Maven 3 (see ["Maven: Password Encryption"][30]), but adds
+improvements like a `decrypt` functionality.
+A brought overview about the problems in Maven 3 and the solution in Maven 4 can be found in the
+article ["Handling sensitive data in Maven"][31] by Maven maintainer Tamás Cservenák.
+
+### Maven Resolver
+
+The [Maven Artifact Resolver][28] is a library for working with artifact repositories and dependency resolution.
+Maven 4 will include the new 2.0 release of this library, which contains more than 150 fixes, upgrades and improvements,
+e.g. a Java native HTTP-Client - thanks to lift of the Java version to JDK 17!
+See the project page for more information!
Review Comment:
Hmm, line 381 contains the link to the project page. But yeah sounds a bit weired. Will remove it.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894083867
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's new in Maven 4?
+
+Maven is over 20 years old and is one of the most used build-tool in the Java world.
+Since all the years one important rule was the highest backward-compatibility as possible, especially with
+its [POM-schema with Model version 4.0.0][2], used for the build itself, but also by consumers.
+This made Maven more than a tool, but a whole ecosystem with a lot of things depended on the POM, esp. the Maven Central
+repository, other build tools and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare to changes which are impossible nowadays, like a complete new build schema.
+
+Another pain point of Maven 3 is a code base with a lot of deprecated, convoluted, non performant and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebases contains old Java code that can be optimized nowadays, but also old
+dependencies and bad API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM-Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction the Model version 4.0.0 is used not only for the build, but also by consumers of the
+artifact.
+But several contents of the POM are only necessary for the build while others like the dependencies are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As names suggest the "Build-POM" will contain all information needed for to build the artifact, e.g. used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep those which are really needed to use the artifact, e.g. dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4 a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others got marked as deprecated.
+To not break the ecosystem this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as like every software update - it's suggested to update them to 4.1.0, e.g. to avoid problems when deprecated
+things get removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 till today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files the wording "Maven project" is used.
+However, project containing multiple parts, e.g. an API and a client, each of those parts was called "module" and listed
+in the `<modules>` section of the POM, leading to the terms of "multi-module project".
+This wording introduced some inconsistency, especially as projects with any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9 the term "module" raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>`analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency managing BOMs.
+While the new type is only available with model Version 4.1.0 the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2004][5].
+
+**Note**: With Maven 4 it's also possible to exclude dependencies which are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven4 importing BOMs with classifier is now possible.
+Therefore, Maven team suggests that projects BOMs be generated as classified artifacts (see Maven build "skinny" vs "
Review Comment:
@cstamas Can you please add a comment about this. I introduced this sentence based on your feedback on my proposal (https://github.com/Bukama/MavenStuff/pull/1/files).
Info: The terms "skinny" and "fat" BOMs are not used in the Maven dependency guide (yet) https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html
I only know the terms in combination with skinny WARs etc.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "cstamas (via GitHub)" <gi...@apache.org>.
cstamas commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894104074
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's new in Maven 4?
+
+Maven is over 20 years old and is one of the most used build-tool in the Java world.
+Since all the years one important rule was the highest backward-compatibility as possible, especially with
+its [POM-schema with Model version 4.0.0][2], used for the build itself, but also by consumers.
+This made Maven more than a tool, but a whole ecosystem with a lot of things depended on the POM, esp. the Maven Central
+repository, other build tools and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare to changes which are impossible nowadays, like a complete new build schema.
+
+Another pain point of Maven 3 is a code base with a lot of deprecated, convoluted, non performant and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebases contains old Java code that can be optimized nowadays, but also old
+dependencies and bad API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM-Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction the Model version 4.0.0 is used not only for the build, but also by consumers of the
+artifact.
+But several contents of the POM are only necessary for the build while others like the dependencies are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As names suggest the "Build-POM" will contain all information needed for to build the artifact, e.g. used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep those which are really needed to use the artifact, e.g. dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4 a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others got marked as deprecated.
+To not break the ecosystem this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as like every software update - it's suggested to update them to 4.1.0, e.g. to avoid problems when deprecated
+things get removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 till today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files the wording "Maven project" is used.
+However, project containing multiple parts, e.g. an API and a client, each of those parts was called "module" and listed
+in the `<modules>` section of the POM, leading to the terms of "multi-module project".
+This wording introduced some inconsistency, especially as projects with any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9 the term "module" raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>`analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency managing BOMs.
+While the new type is only available with model Version 4.1.0 the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2004][5].
+
+**Note**: With Maven 4 it's also possible to exclude dependencies which are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven4 importing BOMs with classifier is now possible.
+Therefore, Maven team suggests that projects BOMs be generated as classified artifacts (see Maven build "skinny" vs "
Review Comment:
Our stance (@gnodet could chime in when online) is following: BOMs should be _generated_ and _not reused within reactor_ (see issues). Also, crafting BOMs has special requirements regarding parent POM and so on. Users seems "tempted" to create BOMs within reactor (is fine, as long BOM meant for "downstream consumption only"), but then they want to reuse BOM in same way as any external BOM would be reused: by importing it within reactor. But, importing within reactor causes "build peculiarities" usually unexpected to users. Hence, we think that _generating BOMs_ simply prevents the two issues, as reactor dependendencies should be managed using inheritance, as it was always the case with Maven. Appearance of BOMs simply caused this "boost of creativity", to reuse them within reactor, but also publish them to downstream users, and it is wrong. Hence, Maven 4 shows an "example", and generates it's own BOMs. Related https://issues.apache.org/jira/browse/MNG-8012 and https://issues.apac
he.org/jira/browse/MNG-8009
In short: only external BOMs should be imported to reactor.
As per "what is a BOM", there is a split among us as can be seen in this old PR: https://github.com/apache/maven/pull/689
For some, "[BOM represents only the set of modules of a multimodule](https://github.com/apache/maven/pull/689#issuecomment-1061640064)" (only the reactor, so to say) while for others (@gnodet and me included) "BOM is bill of materials", so full stack: if I do an extension for Maven version X, I want same version of Resolver, Logging, Sisu etc that Maven X use as well... Similarly, look at all our plugins: after version property defining Maven version that plugins builds against, property is usually followed by a section with bunch of "keep in lockstep with Maven" version properties for logging, resolver, etc. All this is just noise and should not be needed. Hence, the "skinny" (first definition) vs "fat" (second definition). In fact, Maven4 generates both now, so pleases both parties.
Of course, Maven 4 build generated BOMs can be used only in Maven 4 builds, as only Maven 4 allows importing BOMs with classifiers... So for Maven3, this is still an issue.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MNGSITE-550 What's new in Maven 4? [maven-site]
Posted by "mthmulders (via GitHub)" <gi...@apache.org>.
mthmulders commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1894579524
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# What's new in Maven 4?
+
+Maven is over 20 years old and is one of the most used build-tool in the Java world.
+Since all the years one important rule was the highest backward-compatibility as possible, especially with
+its [POM-schema with Model version 4.0.0][2], used for the build itself, but also by consumers.
+This made Maven more than a tool, but a whole ecosystem with a lot of things depended on the POM, esp. the Maven Central
+repository, other build tools and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare to changes which are impossible nowadays, like a complete new build schema.
+
+Another pain point of Maven 3 is a code base with a lot of deprecated, convoluted, non performant and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebases contains old Java code that can be optimized nowadays, but also old
+dependencies and bad API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM-Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction the Model version 4.0.0 is used not only for the build, but also by consumers of the
+artifact.
+But several contents of the POM are only necessary for the build while others like the dependencies are also needed by
+the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As names suggest the "Build-POM" will contain all information needed for to build the artifact, e.g. used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep those which are really needed to use the artifact, e.g. dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4 a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others got marked as deprecated.
+To not break the ecosystem this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as like every software update - it's suggested to update them to 4.1.0, e.g. to avoid problems when deprecated
+things get removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 till today, all build information is stored in the POM, short for "Project Object Model".
+Together with build folders and other files the wording "Maven project" is used.
+However, project containing multiple parts, e.g. an API and a client, each of those parts was called "module" and listed
+in the `<modules>` section of the POM, leading to the terms of "multi-module project".
+This wording introduced some inconsistency, especially as projects with any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9 the term "module" raised additional confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>`analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency managing BOMs.
+While the new type is only available with model Version 4.1.0 the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2004][5].
+
+**Note**: With Maven 4 it's also possible to exclude dependencies which are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven4 importing BOMs with classifier is now possible.
+Therefore, Maven team suggests that projects BOMs be generated as classified artifacts (see Maven build "skinny" vs "
+fat" BOM).
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison about which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply for artefacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations, where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g. when
+condition based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Everytime a Maven build is executed it has to determine the projects root so identify things like the parent project,
+directory information and so on.
+To "help" Maven finding the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project specific configuration to run Maven, e.g. a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4 there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds the boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false) the directory of this POM file is considered the root directory.
+
+Another pain point in relation of the root directly is that until Maven 4 there was no official variable to make use of
+the root folder in your POM files, e.g. when you want to define the path to a `checkstyle-suppressions.xml` file for the
+checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined it should always have the same value for a given project, whereas the value of the`topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subprojects' own base directory, which was and is still accessibly via the `${basedir}` property for the usage in POM
+files and will always have a value.
+
+**Note:** In the past some people "hacked" workarounds for the`rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4 those "hacks" will most probably not work anymore, because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing central repository, the Build-POM should be
+able to evolve.
+This includes allowing the use of alternate syntaxes, by having Maven 4 providing a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects which uses this features is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected it's no longer required to define the parent versions in each subproject, when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parents and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partly supported usage of CI-friendly variables, e.g. `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4 no additional plugin is needed anymore, but full build-in support is provided.
+You can now use variables as versions in your configuration, e.g.
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by a `maven.config` file
+or as a parameter, e.g. `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent from one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuild too).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due the long-stand
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended to not use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully build subprojects when the overall build failed, and will skip to rebuild
+those if you resume the build.
+With Maven 4 it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g. Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve the daily work with those.
+Thanks to [MNG-6754][14] all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3 each subproject was having a different one.
+This should make it easier to identify the archives which belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in the situation where some (successfully
+build) subprojects where deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users are expecting:
+Only deploy when all subprojects were build successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK, but also comes with a more secure runtime as Java 17 includes more security features earlier versions.
+
+**Important note**: Java 17 will only be needed to **run Maven**!
+You will still be able to compile against older Java versions using the same [compiler plugin configuration][6] as
+before!
+If this does not fit your requirements, because you need to compile against or using another JDK, please have a look at
+the [Guide to Using Toolchains][7] (or the article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten
+Mulders).
+
+*Side information: The ballot about the required Java version was hold in March 2024, shortly before Java 22 was
+released.
+One reason Java 17 was chosen over Java 21, because it was (at this time) the second last Java version for which many
+vendors offer long-term-support.*
+
+### Application maintenance
+
+As with every update, especially major ones, large application maintenance happens, containing huge code, API and
+dependency updates and even removals.
+For example the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates contain not only usages of newer Java language features, but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing things that either never should have worked or were only kept for backward-compatibility
+already in Maven 3, e.g. using `${pom.*}` expressions.
+Maven own Super POM was also upgrading, which declares new default versions of Maven's core plugins.
+
+**Note**: Due upgrading the default versions of Maven plugins, your build might behave different that before, even if
+you didn't purposely change anything.
+To avoid this situation you should always define fixed versions of all the plugins you use!
+By doing this you are in control of your build - at the costs of being responsible to upgrade the versions yourself.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM!
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which will break the build when at least one log message
+matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument of a log level severity, e.g. `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so the `?` argument was added to the profile parameter.
+When using this the build won't break, but an information will be printed twice (at the start and the end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more and flexible ways to activate profiles, by providing condition based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+Up to Maven 3 the lifecycle was mathematical graph.
+This changed with Maven 4 where the lifecycle is defined as a tree of phases.
+This allows a more consistent execution of dependent phases, e.g. `compile` must execute after `compile-only` project
+dependencies have reached the `ready` phase, but also "skipping" phases (in comparison to the old graph), e.g. `deploy`
+an artifact without `install`ing it to the user repository.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before` and `after` phase, allowing plugins to bind themselves to those by adding their
+prefixes to the name of the main phase name.
+For example, if you want to set up test data before running your integration test you could execute stuff during the
+`before-integration-test` phase.
+
+If this is not enough, maybe because you want to do multiple things inside the same phase, you can order each execution
+inside a phase by using square brackets with an Integer at the end of the phase name, e.g.
+
+```
+before-integration-test[100]
+before-integration-test[200]
+```
+
+**Warning**: The conceptional `pre-*` and `post-*` phases, wich were only available to selected phases and homogeneously
+named are deprecated - don't use them (anymore)!
+This becomes even more important when you were binding a plugin to the `post-*` phase of a lifecycle phase, because the
+`pre-*` phase of the phase you really would like to bind to did not exist, e.g. binding to `process-resources` phase,
+because there was no `pre-compile`one.
+
+## Maven plugins, security and tools
+
+### Maven plugins
+
+As written above Maven 4 will contain huge code and API updates, resulting in breaking (very) old Maven plugins, which
+were not updated to the recommended APIs.
+Major changes regarding plugins contain a now proper immutable plugin model together with a changed plugin API.
+The updated API provides hints as a preparation for Maven 4.
+You can enable them passing the following argument to your build: `-Dmaven.plugin.validation=verbose`.
+You should also only rely on the official Maven BOMs when developing plugins.
+If a plugin still relies on long time deprecated and now removed Plexus dependency resolution, it will no longer work
+and needs to be updated to JSR-330 - see [Maven & JSR-330][26] for further information.
+
+**Advice**: If you are maintaining a Maven plugin, you should test it with Maven 3.9.x, have a close look at upcoming
+warnings and update the plugin.
+
+### Improved encryption
+
+Security is important and storing unencrypted passwords is bad.
+Maven 3's password encryption has several serious issues and could rather be call a “password obfuscation”.
+Maven 4 instead got a fully redone encryption, based on Maven Encryption (`mvnenc`) - a standalone CLI tool.
+As for now it provides functionally equivalent operations as Maven 3 (see ["Maven: Password Encryption"][30]), but adds
+improvements like a `decrypt` functionality.
+A brought overview about the problems in Maven 3 and the solution in Maven 4 can be found in the
+article ["Handling sensitive data in Maven"][31] by Maven maintainer Tamás Cservenák.
+
+### Maven Resolver
+
+The [Maven Artifact Resolver][28] is a library for working with artifact repositories and dependency resolution.
+Maven 4 will include the new 2.0 release of this library, which contains more than 150 fixes, upgrades and improvements,
+e.g. a Java native HTTP-Client - thanks to lift of the Java version to JDK 17!
+See the project page for more information!
+
+### Maven Shell
+
+When you run any `mvn` the full chain of booting Java, Maven, load config, do the work, tear down and exit the process
+is done - **every single time**.
+To improve performance and reduce build time you can use the [Maven Daemon][29] (`mvnd`), which manages a pool of N
+resident Maven processes.
+With Maven 4 you can also use the brightly polished "Maven Shell" (`mvnsh`), which will keep exactly one resident Maven
+process as long as the shell is opened.
+Stay tuned for more information about this!
Review Comment:
I'm sorry, I meant to suggest only to keep the last sentence out. I do appreciate that you mentioned the Maven shell - it's just that I found the "stay tuned" a little less helpful.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1896786185
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicate code
+which costs the volunteers who maintain Maven a lot of time.
+This means that the Maven codebase contains not only old Java code that can be optimized nowadays but also old
Review Comment:
> None of this is likely to result in noticeably faster code.
>
> Improved GC and security updates come from running in a new JDK, not from using a higher language level or new language features.
Optimized code and faster code are (like a rectangel and square) not the same - at least not for me.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "elharo (via GitHub)" <gi...@apache.org>.
elharo commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1896763343
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicate code
+which costs the volunteers who maintain Maven a lot of time.
+This means that the Maven codebase contains not only old Java code that can be optimized nowadays but also old
Review Comment:
None of this is likely to result in noticeably faster code.
Improved GC and security updates come from running in a new JDK, not from using a higher language level or new language features.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on PR #598:
URL: https://github.com/apache/maven-site/pull/598#issuecomment-2559824408
> Consider the audience of this document. This simply is not relevant to someone who simply wants to use Maven to build their code. It's only relevant to the people developing Maven and that's not who this is written for.
I slightly disagree on that: The audience of this document are all Maven users - those who only want to run their build, but also those who want to know more about the changes, are responsible for build management in their teams, etc (I think someone called them "power users"). If we only considers those who "blindly" use Maven, we don't need the article at all. They are those who still run Maven 3.3.9 and `mvn clean install` because that's what they've read in a tutorial or what was told them years ago.
> I'm not sure we can expect people reading this document to already know the difference between build and consumers. This should probably be carefully explained right up front.
>
What do you think about
```
Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially with its [POM-schema with Model version 4.0.0][2].
This is very important, because POM files with this schema version are not only used for the build of the own project.
Projects, using 3rd party libraries, also rely on the POM files of those, as it contains information needed to successfully run their own builds.
Those projects are called "(a dependency) consuming projects".
```
> Also, "consumers" is a strange term here. I might consider dependents instead, but either way it does need to be defined.
Used the term "consumers" due the terms the committers introduced when developing this feature.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1898716596
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
Review Comment:
> exclamation point
Changed (Sorry I'm so excited about automatic versioning 😍 )
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "elharo (via GitHub)" <gi...@apache.org>.
elharo commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1912180483
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
Review Comment:
Ping
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
Review Comment:
Ping
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
Review Comment:
Ping
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
Review Comment:
Ping
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old, and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
Review Comment:
Ping
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 might produce a Consumer-POM based on version 4.1.0, e.g., when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory variables
+
+Every time a Maven build is executed, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official variable to make use
+of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for
+the checkstyle plugin.
+Maven 4 now provides official variables to reference the root directory in your POM configuration.
+The following table shows the official variables.
+
+| Variable | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these variables differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is
+therefore related to the folder from where you start Maven.
+As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn`
+folder is defined or the `root` attribute is set to true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+variable can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which was and is still accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` variables, mostly by using internal
+variables.
+Starting with Maven 4, those "hacks" will most probably not work anymore because some of those variables were removed or
+at least marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 Consumer-POM is set in stone for accessing the central repository, the Build-POM should
+be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow the usage of a different file as the POM and allow a custom
+syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This is also extended to dependencies of project own subprojects and reduces the need to update POM files for new
+versions even more!
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed anymore; full built-in support is provided.
+You can now use variables as versions in your configuration, e.g.,
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+Of course, you have to provide a value for this variable when starting the build, for example by using a `maven.config`
+file or as a parameter, e.g., `mvn verify -Drevision=4.0.1`, which is commonly done in CI pipelines.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the
+others and its own build failed for whatever reason.
+Maven was telling the user to (fix the error and then) resume the build with
+`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject
+couldn't be found (as it was not rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**It is recommended not to use `mvn clean install`, but `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (e.g., Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where some (successfully
+built) subprojects were deployed to the (local or remote) repository, but failed subprojects were obviously not.
+This was finally changed in Maven 4 to the way most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Java 17 required to run Maven
+
+The required Java version to run Maven 4 will be Java 17.
+This not only allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK but also comes with a more secure runtime as Java 17 includes more security features than earlier versions.
Review Comment:
You can run Maven 3 in Java 17 and get all those updates. None of them are specific to Maven and Maven 4 doesn't enable any of them compared to Maven 3.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1915444219
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
Review Comment:
From my experience and the feedback I got of writing all kind of software project related articles addressing developers, managers or customers for almost 20 years an introduction into articles or documents like this helps the reader a lot.
I accept that you have another standing about this, but as the author I won't drop the introduction, but rather accept that the PR gets declined.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on PR #598:
URL: https://github.com/apache/maven-site/pull/598#issuecomment-2599634998
> This PR is for big page (long content) that is to be published without any predecessor, and PR goes for over a month now with long discussions that is hard to track.
>
> Why not just merge it, and continue improving it factually and stylistically in step by step instead?
I would appreciate this, esp. as you already linked this PR in a external project's PR.
I guess @elharo and @gnodet need to decide as they are maintainers who requested changes (however @gnodet has not mentioned what - so this could be done in a separate PR more easily).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1915418996
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,474 @@
+# What's New in Maven 4?
+
+Maven is over 20 years old and is one of the most used build tools in the Java world.
+Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially
+with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers.
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven
+Central repository, other build tools, and IDEs.
+But this stable schema comes at a price - the lack of flexibility.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema.
+
+Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code
+which costs the volunteers who maintain Maven a lot of time.
+This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old
+dependencies and poor API design of its own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the
+artifact.
+However, several contents of the POM are only necessary for the build while others, like the dependencies, are also
+needed by the consumer.
+Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM".
+As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and
+their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those.
+This POM will only keep what is really needed to use the artifact, e.g., dependency information.
+
+**Note**: See below for a comparison of the content of both POMs.
+
+### Model version 4.1.0
+
+With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven (
+and of course IDEs).
+Therefore, with Maven 4, a new Model version 4.1.0 is introduced.
+This version introduces some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use
+version 4.0.0.
+This means Maven will generate the Consumer-POM during the build.
+
+**Note**: Maven 4 will of course continue to build your model version 4.0.0 project!
+There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features.
+But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated
+features are removed in future updates.
+
+### Modules are now subprojects
+
+From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object
+Model".
+Together with build folders and other files, the wording "Maven project" is used.
+However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module"
+and listed in the `<modules>` section of the POM, leading to the terms "multi-module project".
+This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called "
+single-module".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion.
+
+Maven 4 gets rid of this by naming "modules" as what they are - subprojects.
+Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element
+`<modules>`.
+
+**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a
+Maven project with or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more
+precisely between "parent POMs" and dependency-managing BOMs.
+While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model
+4.0.0) POM file!
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build (in other words, "you should import only external BOMs") or it may break your build (as
+shown in [MNG-8009][32]).
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing Build-POM and Consumer-POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"!
+* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in
+ the Build-POM in the future.
+
+| Content | Build-POM | Consumer-POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| Properties | ✅ | ❌ |
Review Comment:
Don't understand what you mean by this.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1946675915
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,476 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is the most widely used build tool in the Java world.
+Throughout the years, Maven has maintained backward compatibility, especially of its [POM file][2] with Model version
+4.0.0.
+
+The POM file fulfills two needs.
+First, the POM holds all the information and configuration, which are needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, for example dependencies, which are needed by projects which depend on the
+artifact.
+These dependent projects are called the "consumers".
+
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+Thus, any change in the POM's schema forces each participant of the ecosystem to either adopt the change or drop
+support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+In order for Maven to evolve, it's necessary to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## Required Java version
+
+Maven 4 requires Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements.
+
+**Important note**: Java 17 is only needed to **run Maven**!
+You can still compile against older Java versions using the same [compiler plugin configuration][6] as before.
+If you need to compile against or use another JDK, see the [Guide to Using Toolchains][7] (or the
+article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten Mulders).
+
+## POM Changes
+
+### Consumer POM
+
+Maven 4 generates a stripped down consumer POM that removes build information not needed by consumers, and deploys this
+to the remote repository.
+It does not deploy the `pom.xml` used to build the project.
+
+### Model version 4.1.0
+
+Maven 4 updates the POM version to 4.1.0 which defines the namespace `http://maven.apache.org/POM/4.1.0`.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the build POM, while the consumer POM will still use
+version 4.0.0.
+Maven generates the consumer POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 if you don't need to use the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project built with Maven.
+The [top level directory][32] of a Maven project contains at least the source folder `src` and the project's POM file
+`pom.xml`.
+A Maven project may have other Maven projects within subdirectories, each with its own `pom.xml` file.
+Each project within a subdirectory is called a "subproject".
+
+Example: Project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects unless they are linked from the root POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+Projects which have at least one subproject are called "multi-module projects", while those which do not have any
+subprojects are called "single module projects".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated `bom` packaging type to provide a [Bill of Materials BOM][4].
+This now differentiates between parent POMs and dependency-managing BOMs.
+The new type is only available as a build POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible consumer POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build.
+In other words: you should only import external BOMs.
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing build POM and consumer POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "consumer POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, for example plugin configuration!
+* Some of the build-related content which is (as of now) still available in the consumer POM might be available only in
+ the build POM in the future.
+
+| Content | Build POM | Consumer POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a consumer POM based on version 4.1.0, for example
+when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, for example a `maven.config` or
+`jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the build POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, for example when you want to define the path to a `checkstyle-suppressions.xml`
+file for the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+current working directory.
+The `rootDirectory` can only contain a value when either a `.mvn` directory is defined or the `root` attribute is set to
+true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4 those properties were removed or marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 consumer POM is set in stone, the build POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, like `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration.
+
+Example
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, for example `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects can cause confusion in Maven 3.
+When the build of subproject B, which requires subproject A, is failing for whatever reason, Maven 3 is telling
+the user to fix the error and then resume the build with `--resume-from :<nameOfTheFailingSubproject>`.
+But doing this instantly fails the build again, because the required subproject A couldn't be found (as it was not
+rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (for example Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where successfully
Review Comment:
@lbruun Reverted as the default value is indeed now `true`. I was not aware that the changes were already in the master branch, because I thought the Maven 4 branch of the deploy plugin is the current state for Maven 4 - but I was wrong. Added a note that the default value of `deployAtEnd` is now true.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "kwin (via GitHub)" <gi...@apache.org>.
kwin commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1931927951
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,477 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is the most widely used build tool in the Java world.
+Throughout the years, Maven has maintained backward compatibility, especially of its [POM file][2] with Model version
+4.0.0.
+
+The POM file fulfills two needs.
+First, the POM holds all the information and configuration, which are needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, for example dependencies, which are needed by projects which depend on the
+artifact.
+These dependent projects are called the "consumers".
+
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+Thus, any change in the POM's schema forces each participant of the ecosystem to either adopt the change or drop
+support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+In order for Maven to evolve, it's necessary to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## Required Java version
+
+Maven 4 requires Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
Review Comment:
rather the JRE (JDK is only optionally used with m-compiler-p).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "kwin (via GitHub)" <gi...@apache.org>.
kwin commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1932012376
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,477 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is the most widely used build tool in the Java world.
+Throughout the years, Maven has maintained backward compatibility, especially of its [POM file][2] with Model version
+4.0.0.
+
+The POM file fulfills two needs.
+First, the POM holds all the information and configuration, which are needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, for example dependencies, which are needed by projects which depend on the
+artifact.
+These dependent projects are called the "consumers".
+
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+Thus, any change in the POM's schema forces each participant of the ecosystem to either adopt the change or drop
+support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+In order for Maven to evolve, it's necessary to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## Required Java version
+
+Maven 4 requires Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 is only needed to **run Maven**!
+You can still compile against older Java versions using the same [compiler plugin configuration][6] as before.
+If you need to compile against or use another JDK, see the [Guide to Using Toolchains][7] (or the
+article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten Mulders).
+
+## POM Changes
+
+### Consumer POM
+
+Maven 4 generates a stripped down consumer POM that removes build information not needed by consumers, and deploys this
+to the remote repository.
+It does not deploy the `pom.xml` used to build the project.
+
+### Model version 4.1.0
+
+Maven 4 updates the POM version to 4.1.0 which defines the namespace `http://maven.apache.org/POM/4.1.0`.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the build POM, while the consumer POM will still use
+version 4.0.0.
+Maven generates the consumer POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 if you don't need to use the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project built with Maven.
+The [top level directory][32] of a Maven project contains at least the source folder `src` and the project's POM file
+`pom.xml`.
+A Maven project may have other Maven projects within subdirectories, each with its own `pom.xml` file.
+Each project within a subdirectory is called a "subproject".
+
+Example: Project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects unless they are linked from the root POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+Projects which have at least one subproject are called "multi-module projects", while those which do not have any
+subprojects are called "single module projects".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated `bom` packaging type to provide a [Bill of Materials BOM][4].
+This now differentiates between parent POMs and dependency-managing BOMs.
+The new type is only available as a build POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible consumer POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build.
+In other words: you should only import external BOMs.
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing build POM and consumer POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "consumer POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, for example plugin configuration!
+* Some of the build-related content which is (as of now) still available in the consumer POM might be available only in
+ the build POM in the future.
+
+| Content | Build POM | Consumer POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a consumer POM based on version 4.1.0, for example
+when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, for example a `maven.config` or
+`jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the build POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, for example when you want to define the path to a `checkstyle-suppressions.xml`
+file for the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+current working directory.
+The `rootDirectory` can only contain a value when either a `.mvn` directory is defined or the `root` attribute is set to
+true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4 those properties were removed or marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 consumer POM is set in stone, the build POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, like `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration.
+
+Example
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, for example `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects can cause confusion in Maven 3.
+When the build of subproject B, which requires subproject A, is failing for whatever reason, Maven 3 is telling
+the user to fix the error and then resume the build with `--resume-from :<nameOfTheFailingSubproject>`.
+But doing this instantly fails the build again, because the required subproject A couldn't be found (as it was not
+rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
+Instead, use `mvn verify` for your regular builds!**
+
+To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a
+build from the subproject that last failed.
+So you don't have to manually pass the name of the failed subproject as the starting point to resume from.
+The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding
+those if you resume the build.
+With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to
+execute tools (for example Jetty) on/with certain subprojects, but not on every subproject.
+See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example.
+
+### Further improvements
+
+Further improvements to subprojects will also improve daily work with them.
+Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven
+3, each subproject had a different one.
+This should make it easier to identify the archives that belong together.
+When using Maven 3, deploying a project with multiple subprojects could end up in a situation where successfully
+built subprojects were deployed to the (local or remote) repository, but failed subprojects were not.
+This was finally changed in Maven 4 to what most users expect:
+Only deploy when all subprojects are built successfully.
+
+## Workflow, lifecycle and runtime changes
+
+### Application maintenance
+
+As with every major update, extensive application maintenance has occurred, including significant code, API, and
+dependency updates.
+For example, the "Plexus Containers" dependency injection was removed - after being deprecated since Maven 3.2 (2010)!
+Code updates include not only newer Java language features but also changes to make maintenance easier and
+less time-consuming.
+This also includes removing features that either should never have worked or were only kept for backward compatibility
+in Maven 3, for example using `${pom.*}` expressions.
+Maven's own Super POM was also upgraded, which declares new default versions of Maven's core plugins.
+
+**Note**: Due to upgrading the default versions of Maven plugins, your build might behave differently than before, even
+if you didn't purposely change anything.
+To avoid this situation, always define fixed versions of all the plugins you use.
+By doing this, you are in control of your build.
+Maven 4 will issue a warning if you rely on default versions defined in Maven's Super POM.
+
+### "Fail on severity" parameter
+
+Maven 4 introduces a "fail on severity" build parameter, which breaks the build when the severity of at least one log
+message matches the given argument.
+
+The parameter can either be used by its full name (`--fail-on-severity`) or as a short handle (`-fos`).
+The parameter is followed by an argument specifying a log level severity, for example, `WARN`.
+
+### Improvements to profiles
+
+Trying to use a nonexistent profile in a build causes the build to fail, as the following command line snippet shows:
+
+```
+> mvn compile -Pnonexistent
+[ERROR] The requested profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 introduces the possibility to only use profiles when they exist.
+To do so, the `?` argument was added to the profile parameter.
+When using this, the build won't break.
+Instead, an information message will be printed twice (at the start and end).
+See the following snippet for an example:
+
+```
+> mvn compile -P?nonexistent
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+[...]
+[INFO] BUILD SUCCESS
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] Total time: 0.746 s
+[INFO] Finished at: 2024-12-14T13:24:15+01:00
+[INFO] ----------------------------------------------------------------------------------------------------------------
+[INFO] The requested optional profiles [nonexistent] could not be activated or deactivated because they do not exist.
+```
+
+Maven 4 also introduces more flexible ways to activate profiles by providing condition-based activation.
+See [MNG-8286][27] for more information about supported functions.
+
+### Lifecycle changes
+
+#### Lifecycle changed from graph to tree
+
+In Maven 3 the lifecycle is an ordered list containing all phases.
+This changed with Maven 4, where the lifecycle is defined as a tree of phases.
+This allows for more fine-grained execution of dependent phases.
+For example, the `compile` phase must execute after `compile-only` project dependencies have reached the `ready` phase.
+Maven 4 also allows to skip phases (in comparison to the old graph).
+For example, it's possible to `deploy` an artifact without `install`ing it to the user repository.
+
+For compatibility, the execution behavior is not really changed by default compared to Maven 3.
+In order to actually leverage the new tree-based lifecycle, the user has to enable the concurrent builder using
+`-b concurrent`.
+Running with the concurrent builder will allow finer grained dependency instead of the usual Maven 3 per-project
+dependency.
+With the usual builders and run `mvn verify`, a project will run up to the verify phase, before a dependent project can
+start being built, whereas the concurrent builder will allow a dependant project to be built as soon as the dependencies
+are at the `ready` phase.
+
+#### Pre- and post-phases, ordering of executions
+
+Every lifecycle phase now has a `before:` and an `after:` phase, allowing plugins to bind themselves to those.
+For example, if you want to set up test data before running your integration tests, you could execute tasks during the
+`before:integration-test` phase.
+
+If this is not enough, perhaps because you want to do multiple things inside the same phase, you can order each
+execution inside a phase by using square brackets with an integer at the end of the phase name.
+
+Example
+
+```
+before:integration-test[100]
+before:integration-test[200]
+```
+
+**Warning**: The conceptual `pre-*` and `post-*` phases, which were only available for selected phases and had
+inconsistent naming, are deprecated.
+Don't use them!
+This becomes even more important if you are binding a plugin to the `post-*` phase of a lifecycle phase because the
+`pre-*` phase of the phase you really want to bind to does not exist, for example, binding to `process-resources` phase
+because there was no `pre-compile` phase.
+
+## Maven plugins, security, and tools
+
+### Maven plugins
+
+As mentioned above, Maven 4 contains significant code and API updates, resulting in breaking changes for (very) old
+Maven plugins that have not been updated to use the recommended APIs.
+Major changes regarding plugins include a proper immutable plugin model together with a revised plugin API.
+The updated API provides hints as preparation for Maven 4.
+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.
+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.
+
+**Advice**: If you are maintaining a Maven plugin, you should test it with Maven 3.9.x.
+Pay close attention to upcoming warnings and update the plugin accordingly.
+
+### Improved encryption
+
+Security is important, and storing unencrypted passwords is bad practice.
+Maven 3's password encryption had several serious issues and could more accurately be called "password obfuscation".
+Maven 4 instead has a completely redone encryption system, based on Maven Encryption (`mvnenc`) - a standalone CLI tool.
Review Comment:
So what API is proposed by Maven for sensitive values e.g. for Mojos or extensions?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1927400104
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,477 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<head>
+ <title>What's new in Maven 4?</title>
+ <meta name="author" content="Matthias Bünger" />
+</head>
+
+# What's new in Maven 4?
+
+Maven is over 20 years old, and is the most widely used build tool in the Java world.
+Throughout the years, Maven has maintained backward compatibility, especially of its [POM file][2] with Model version
+4.0.0.
+
+The POM file fulfills two needs.
+First, the POM holds all the information and configuration, which are needed to build the artifact.
+After the artifact is created, this build information is not relevant anymore.
+Second, the POM also contains information, for example dependencies, which are needed by projects which depend on the
+artifact.
+These dependent projects are called the "consumers".
+
+This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the
+Maven Central repository, other build tools, and IDEs.
+Thus, any change in the POM's schema forces each participant of the ecosystem to either adopt the change or drop
+support.
+Thus, the Maven POM syntax became fixed, unable to change.
+
+> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases,
+>
+>> unable to implement improvements that we imagine will require seriously updating the POM schema…"
+>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite>
+
+In order for Maven to evolve, it's necessary to separate the information needed for the build from the information
+needed by the consumers, but without breaking the ecosystem.
+Maven 4 prepares for this and more.
+
+This article presents and explains major changes brought by Maven 4, grouped into several topics.
+
+## Required Java version
+
+Maven 4 requires Java 17.
+This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the
+JDK.
+
+**Important note**: Java 17 is only needed to **run Maven**!
+You can still compile against older Java versions using the same [compiler plugin configuration][6] as before.
+If you need to compile against or use another JDK, see the [Guide to Using Toolchains][7] (or the
+article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten Mulders).
+
+## POM Changes
+
+### Consumer POM
+
+Maven 4 generates a stripped down consumer POM that removes build information not needed by consumers, and deploys this
+to the remote repository.
+It does not deploy the `pom.xml` used to build the project.
+
+### Model version 4.1.0
+
+Maven 4 updates the POM version to 4.1.0.
+Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated.
+To not break the ecosystem, this version is only available for the build POM, while the consumer POM will still use
+version 4.0.0.
+Maven generates the consumer POM during the build from the build POM.
+
+**Note**: Maven 4 will continue to build your model version 4.0.0 project.
+There is no need to update your POMs to 4.1.0 if you don't need to use the new features.
+
+### Modules are now subprojects
+
+A Maven project is any Java project built with Maven.
+The [top level directory][32] of a Maven project contains at least the source folder `src` and the project's POM file
+`pom.xml`.
+A Maven project may have other Maven projects within subdirectories, each with its own `pom.xml` file.
+Each project within a subdirectory is called a "subproject".
+
+Example: Project A contains a subdirectory which contains its own POM file for project B.
+We say that B is a subproject of A.
+
+However, Maven does not build subprojects unless they are linked from the root POM file.
+In the past this was done by listing each subproject in the `<modules>` section of the parent's POM.
+Projects which have at least one subproject are called "multi-module projects", while those which do not have any
+subprojects are called "single module projects".
+Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional
+confusion inside the Maven community.
+
+Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects.
+Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable,
+`<modules>` element.
+
+**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with
+or without subprojects.
+
+### New packaging type: bom
+
+Maven 4 introduces a dedicated `bom` packaging type to provide a [Bill of Materials BOM][4].
+This now differentiates between parent POMs and dependency-managing BOMs.
+The new type is only available as a build POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3
+compatible consumer POM during the build.
+For an example, see the link above or
+the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5].
+
+**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing
+`<exclusions>` element.
+Also note that in Maven 4, importing BOMs with a classifier is now possible.
+Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the
+`<bomClassifier>` element.
+This means that an imported BOM must **not** come from the same reactor as the current build but be available outside
+the project before the build.
+In other words: you should only import external BOMs.
+That's why Maven 4.0 will show a warning if a BOM comes from the same reactor.
+In the future, this will most probably be changed to make the build fail.
+
+### Comparing build POM and consumer POM
+
+The following table shows a rough comparison of which content is available in which POM type when using Maven 4.
+
+**Notes**:
+
+* The column "consumer POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to
+ contain build information, for example plugin configuration!
+* Some of the build-related content which is (as of now) still available in the consumer POM might be available only in
+ the build POM in the future.
+
+| Content | Build POM | Consumer POM |
+|:-------------------------------------------|:---------:|:------------:|
+| Model version | 4.1.0 | 4.0.0 |
+| 3rd party dependency information | ✅ | ✅ |
+| POM properties | ✅ | ❌ |
+| Plugin configuration | ✅ | ❌ |
+| Repository information | ✅ | ✅ |
+| Project information / environment settings | ✅ | ✅ |
+| Deployment to remote repository | ✅ | ✅ |
+
+**Warning**: There are rare situations where Maven 4 will produce a consumer POM based on version 4.1.0, for example
+when
+condition-based profiles (see below) can't be transformed to version 4.0.0.
+Maven will show a warning in such situations.
+
+### Declaring the root directory and directory properties
+
+Every time Maven executes a build, it has to determine the project's root to identify things like the parent project,
+directory information, and so on.
+To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory.
+This folder is intended to contain project-specific configuration to run Maven, for example a `maven.config` or
+`jvm.config`
+file, and therefore was also considered as the root folder.
+With Maven 4, there is a second option to clearly define the root folder.
+Model version 4.1.0, usable for the build POM, adds a boolean attribute called `root` in the `<project>` element.
+When this attribute is set to true (default is false), the directory of this POM file is considered the root directory.
+
+Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use
+of the root folder in your POM files, for example when you want to define the path to a `checkstyle-suppressions.xml`
+file for the checkstyle plugin.
+Maven 4 now provides official properties to reference the root directory in your POM configuration.
+The following table shows the official properties.
+
+| Property | Scope | Definition | Always |
+|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:|
+| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No |
+| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes |
+| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No |
+
+As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's
+definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the
+current working directory.
+The `rootDirectory` can only contain a value when either a `.mvn` directory is defined or the `root` attribute is set to
+true.
+However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory`
+property can change depending on the execution point.
+
+Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each
+subproject's own base directory, which is accessible via the `${basedir}` property for use in POM
+files and will always have a value.
+
+**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal
+properties.
+Starting with Maven 4 those properties were removed or marked as deprecated.
+See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information.
+
+### Alternate POM syntaxes
+
+While the syntax for the 4.0.0 consumer POM is set in stone, the build POM should be able to evolve.
+This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]),
+which can be implemented as a core extension and allow a custom syntax.
+
+One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25].
+
+## Improvements for subprojects
+
+### Automatic versioning
+
+Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in
+July 2005 and originally planned for Maven 2)!
+As expected, it's no longer required to define the parent versions in each subproject when using the new model version
+4.1.0.
+This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new
+versions even more.
+
+The following code snippet shows the parent and dependency definition without the version tag.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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>
+
+ <parent>
+ <groupId>my.parents.groupId</groupId>
+ <artifactId>my.parents.artifactId</artifactId>
+ </parent>
+
+ <artifactId>myOwnSubprojectArtifactId</artifactId>
+
+ <dependencies>
+ <dependency>
+ <groupId>the.dependent.subproject.groupId</groupId>
+ <artifactId>the.dependent.subproject.artifactId</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+### Full support of CI-friendly variables
+
+Maven 3.5.0 introduced partial support for CI-friendly variables, like `${revision}`, in your POM files.
+However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality.
+Since Maven 4, no additional plugin is needed; full built-in support is provided.
+You can now use variables as versions in your configuration.
+
+Example
+
+```xml
+
+<groupId>my.groupId</groupId>
+<artifactId>my.artifactId</artifactId>
+<version>${revision}</version>
+```
+
+You have to provide a value for this variable when starting the build, for example by using a `maven.config` file.
+In CI pipelines it's commonly done using a parameter, for example `mvn verify -Drevision=4.0.1`.
+
+Maven maintainer Karl Heinz Marbaise shows a larger example in
+his [article "Maven 4 - Part I - Easier Versions" (2024)][21].
+
+### Reactor improvements and fixes
+
+Building a project with multiple subprojects can cause confusion in Maven 3.
+When the build of subproject B, which requires subproject A, is failing for whatever reason, Maven 3 is telling
+the user to fix the error and then resume the build with `--resume-from :<nameOfTheFailingSubproject>`.
+But doing this instantly fails the build again, because the required subproject A couldn't be found (as it was not
+rebuilt).
+Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing
+bug [MNG-6863][11] - which is finally fixed with Maven 4!
+
+**Recommendation: Do not use `mvn clean install`.
Review Comment:
> I think we need to write explicitly somewhere that for the building a subproject we don't need to `install` the root project.
I think https://maven.apache.org/guides/mini/guide-multiple-subprojects-4.html is the correct place for this.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [MNGSITE-550] What's new in Maven 4? [maven-site]
Posted by "Bukama (via GitHub)" <gi...@apache.org>.
Bukama merged PR #598:
URL: https://github.com/apache/maven-site/pull/598
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org