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-unsubscr...@maven.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
