diff --git a/content/markdown/whatsnewinmaven4.md b/content/markdown/whatsnewinmaven4.md new file mode 100644 index 0000000000..d3567e674f --- /dev/null +++ b/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…" +> — [Hervé Boutemy (in Javaadvent 2021)][1] + +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 `` section of the POM, leading to the terms "multi-module project". +This wording introduced some inconsistency, especially as projects without any `` 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 `` analogous to the now deprecated, but still usable, element +``. + +**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 +`` 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 +`` 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 `` 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 + + + 4.1.0 + + + my.parents.groupId + my.parents.artifactId + + + myOwnSubprojectArtifactId + + + + the.dependent.subproject.groupId + the.dependent.subproject.artifactId + + + +``` + +### 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 + +my.groupId +my.artifactId +${revision} +``` + +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 :`, which instantly fails the build again as the needed other subproject +couldn't be found (as it was not rebuilt). +Using `--also-make :` 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 injection, it will no longer work. +It needs to be updated to use JSR-330 - see [Maven & JSR-330][26] for further information. + +**Advice**: If you are maintaining a Maven plugin, you should test it with Maven 3.9.x, pay close attention to upcoming +warnings, and update the plugin accordingly. + +### Improved encryption + +Security is important, and storing unencrypted passwords is bad practice. +Maven 3's password encryption had several serious issues and could more accurately be called "password obfuscation". +Maven 4 instead has a completely redone encryption system, based on Maven Encryption (`mvnenc`) - a standalone CLI tool. +As of now, it provides functionally equivalent operations as Maven 3 (see ["Maven: Password Encryption"][30]) but adds +improvements like a `decrypt` functionality. +A broad overview of the problems in Maven 3 and the solution in Maven 4 can be found in the +article ["Handling sensitive data in Maven"][31] by Maven maintainer Tamás Cservenák. + +### Maven Resolver + +The [Maven Artifact Resolver][28] is a library for working with artifact repositories and dependency resolution. +Maven 4 will include the new 2.0 release of this library, which contains more than 150 fixes, upgrades, and +improvements, e.g., a Java native HTTP-Client - thanks to raising the Java version requirement to JDK 17! +Another major difference compared to Maven 3 is that in the new major version, the resolver is hidden behind the new +Maven API and is no longer used directly by plugins. + +### Maven Shell + +Each time you run an `mvn` command, the entire process chain is executed: booting Java, starting Maven, loading the +configuration, performing the task, tearing down, and exiting — **every single time**. +To improve performance and reduce build times, you can use the [Maven Daemon][29] (`mvnd`), which manages a pool of +resident Maven processes. +With Maven 4, you can also take advantage of the newly defined "Maven Shell" (`mvnsh`), which keeps a single Maven +process running for as long as the shell remains open. + +## Issue overview + +The Maven issue tracker provides a [full list of all resolved issues of Maven 4.0.0][22]. +As of 2024-12-14, not all issues are properly linked to the final release and therefore may not be shown in that list. +If you want to see issues resolved in each individual (alpha/beta/RC) release, please see +the [Maven releases history][10], starting with the alpha versions for Maven 4.0.0. + + + + +[1]: https://www.javaadvent.com/2021/12/from-maven-3-to-maven-5.html + +[2]: https://maven.apache.org/pom.html + +[3]: https://en.wikipedia.org/wiki/Java_Platform_Module_System + +[4]: https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#bill-of-materials-bom-poms + +[5]: https://www.youtube.com/watch?v=ZD_YxTmQ16Q&t=16710s + +[6]: https://maven.apache.org/plugins/maven-compiler-plugin/examples/set-compiler-release.html + +[7]: https://maven.apache.org/guides/mini/guide-using-toolchains.html + +[8]: https://maarten.mulders.it/2021/03/introduction-to-maven-toolchains/ + +[9]: https://issues.apache.org/jira/projects/MNG/issues/MNG-8061 + +[10]: https://maven.apache.org/docs/history.html + +[11]: https://issues.apache.org/jira/browse/MNG-6863 + +[12]: https://issues.apache.org/jira/browse/MNG-6118 + +[13]: https://maarten.mulders.it/2020/11/whats-new-in-maven-4/ + +[14]: https://issues.apache.org/jira/browse/MNG-6754 + +[15]: https://issues.apache.org/jira/browse/MNG-7038 + +[16]: https://github.com/apache/maven/pull/1061 + +[17]: https://issues.apache.org/jira/browse/MNG-624 + +[18]: https://issues.apache.org/jira/browse/MNG-6656 + +[19]: https://issues.apache.org/jira/browse/MNG-7051 + +[20]: https://www.mojohaus.org/flatten-maven-plugin/ + +[21]: https://blog.soebes.io/posts/2024/03/2024-03-31-maven-4-part-i/ + +[22]: https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12316922&version=12346477 + +[23]: https://issues.apache.org/jira/browse/MNG-7879 + +[24]: https://issues.apache.org/jira/browse/MNG-7836 + +[25]: https://github.com/apache/maven-hocon-extension + +[26]: https://maven.apache.org/maven-jsr330.html + +[27]: https://issues.apache.org/jira/browse/MNG-8286 + +[28]: https://maven.apache.org/resolver/ + +[29]: https://github.com/apache/maven-mvnd + +[30]: https://maven.apache.org/guides/mini/guide-encryption.html + +[31]: https://cstamas.org/blog/2024/09/handling-sensitive-data-in-maven/ + +[32]: https://issues.apache.org/jira/browse/MNG-8009 \ No newline at end of file diff --git a/content/site.xml b/content/site.xml index ae5bbb91ad..2d9c2af055 100644 --- a/content/site.xml +++ b/content/site.xml @@ -53,6 +53,7 @@ under the License. +