[
https://issues.apache.org/jira/browse/MNGSITE-550?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17907391#comment-17907391
]
ASF GitHub Bot commented on MNGSITE-550:
----------------------------------------
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
```
> Information about "What's new in Maven 4?"
> ------------------------------------------
>
> Key: MNGSITE-550
> URL: https://issues.apache.org/jira/browse/MNGSITE-550
> Project: Maven Project Web Site
> Issue Type: Improvement
> Reporter: Matthias Bünger
> Priority: Major
>
> A comprehensive article/list of the important changes in Maven 4 is needed.
> ----
>
> Issue based on the slack message / thread, started by [~cstamas]
> {quote}
> More and more times we get questions like "and what is new in Maven4?". We
> have no document that distills the relevant changes. Could someone try to
> collect that in cwiki or somewhere?
> {quote}
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
