Bukama commented on code in PR #598: URL: https://github.com/apache/maven-site/pull/598#discussion_r1941795223
########## content/markdown/whatsnewinmaven4.md: ########## @@ -0,0 +1,476 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +<head> + <title>What's new in Maven 4?</title> + <meta name="author" content="Matthias Bünger" /> +</head> + +# What's new in Maven 4? + +Maven is over 20 years old, and is the most widely used build tool in the Java world. +Throughout the years, Maven has maintained backward compatibility, especially of its [POM file][2] with Model version +4.0.0. + +The POM file fulfills two needs. +First, the POM holds all the information and configuration, which are needed to build the artifact. +After the artifact is created, this build information is not relevant anymore. +Second, the POM also contains information, for example dependencies, which are needed by projects which depend on the +artifact. +These dependent projects are called the "consumers". + +This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the +Maven Central repository, other build tools, and IDEs. +Thus, any change in the POM's schema forces each participant of the ecosystem to either adopt the change or drop +support. +Thus, the Maven POM syntax became fixed, unable to change. + +> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases, +> +>> unable to implement improvements that we imagine will require seriously updating the POM schema…" +>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite> + +In order for Maven to evolve, it's necessary to separate the information needed for the build from the information +needed by the consumers, but without breaking the ecosystem. +Maven 4 prepares for this and more. + +This article presents and explains major changes brought by Maven 4, grouped into several topics. + +## Required Java version + +Maven 4 requires Java 17. +This allows Maven (and its maintainers) to make use of newer language features and improvements. + +**Important note**: Java 17 is only needed to **run Maven**! +You can still compile against older Java versions using the same [compiler plugin configuration][6] as before. +If you need to compile against or use another JDK, see the [Guide to Using Toolchains][7] (or the +article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten Mulders). + +## POM Changes + +### Consumer POM + +Maven 4 generates a stripped down consumer POM that removes build information not needed by consumers, and deploys this +to the remote repository. +It does not deploy the `pom.xml` used to build the project. + +### Model version 4.1.0 + +Maven 4 updates the POM version to 4.1.0 which defines the namespace `http://maven.apache.org/POM/4.1.0`. +Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated. +To not break the ecosystem, this version is only available for the build POM, while the consumer POM will still use +version 4.0.0. +Maven generates the consumer POM during the build from the build POM. + +**Note**: Maven 4 will continue to build your model version 4.0.0 project. +There is no need to update your POMs to 4.1.0 if you don't need to use the new features. + +### Modules are now subprojects + +A Maven project is any Java project built with Maven. +The [top level directory][32] of a Maven project contains at least the source folder `src` and the project's POM file +`pom.xml`. +A Maven project may have other Maven projects within subdirectories, each with its own `pom.xml` file. +Each project within a subdirectory is called a "subproject". + +Example: Project A contains a subdirectory which contains its own POM file for project B. +We say that B is a subproject of A. + +However, Maven does not build subprojects unless they are linked from the root POM file. +In the past this was done by listing each subproject in the `<modules>` section of the parent's POM. +Projects which have at least one subproject are called "multi-module projects", while those which do not have any +subprojects are called "single module projects". +Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional +confusion inside the Maven community. + +Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects. +Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable, +`<modules>` element. + +**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with +or without subprojects. + +### New packaging type: bom + +Maven 4 introduces a dedicated `bom` packaging type to provide a [Bill of Materials BOM][4]. +This now differentiates between parent POMs and dependency-managing BOMs. +The new type is only available as a build POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3 +compatible consumer POM during the build. +For an example, see the link above or +the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5]. + +**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing +`<exclusions>` element. +Also note that in Maven 4, importing BOMs with a classifier is now possible. +Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the +`<bomClassifier>` element. +This means that an imported BOM must **not** come from the same reactor as the current build but be available outside +the project before the build. +In other words: you should only import external BOMs. +That's why Maven 4.0 will show a warning if a BOM comes from the same reactor. +In the future, this will most probably be changed to make the build fail. + +### Comparing build POM and consumer POM + +The following table shows a rough comparison of which content is available in which POM type when using Maven 4. + +**Notes**: + +* The column "consumer POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to + contain build information, for example plugin configuration! +* Some of the build-related content which is (as of now) still available in the consumer POM might be available only in + the build POM in the future. + +| Content | Build POM | Consumer POM | +|:-------------------------------------------|:---------:|:------------:| +| Model version | 4.1.0 | 4.0.0 | +| 3rd party dependency information | ✅ | ✅ | +| POM properties | ✅ | ❌ | +| Plugin configuration | ✅ | ❌ | +| Repository information | ✅ | ✅ | +| Project information / environment settings | ✅ | ✅ | +| Deployment to remote repository | ✅ | ✅ | + +**Warning**: There are rare situations where Maven 4 will produce a consumer POM based on version 4.1.0, for example +when +condition-based profiles (see below) can't be transformed to version 4.0.0. +Maven will show a warning in such situations. + +### Declaring the root directory and directory properties + +Every time Maven executes a build, it has to determine the project's root to identify things like the parent project, +directory information, and so on. +To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory. +This folder is intended to contain project-specific configuration to run Maven, for example a `maven.config` or +`jvm.config` +file, and therefore was also considered as the root folder. +With Maven 4, there is a second option to clearly define the root folder. +Model version 4.1.0, usable for the build POM, adds a boolean attribute called `root` in the `<project>` element. +When this attribute is set to true (default is false), the directory of this POM file is considered the root directory. + +Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use +of the root folder in your POM files, for example when you want to define the path to a `checkstyle-suppressions.xml` +file for the checkstyle plugin. +Maven 4 now provides official properties to reference the root directory in your POM configuration. +The following table shows the official properties. + +| Property | Scope | Definition | Always | +|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:| +| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No | +| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes | +| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No | + +As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's +definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the +current working directory. +The `rootDirectory` can only contain a value when either a `.mvn` directory is defined or the `root` attribute is set to +true. +However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory` +property can change depending on the execution point. + +Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each +subproject's own base directory, which is accessible via the `${basedir}` property for use in POM +files and will always have a value. + +**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal +properties. +Starting with Maven 4 those properties were removed or marked as deprecated. +See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information. + +### Alternate POM syntaxes + +While the syntax for the 4.0.0 consumer POM is set in stone, the build POM should be able to evolve. +This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]), +which can be implemented as a core extension and allow a custom syntax. + +One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25]. + +## Improvements for subprojects + +### Automatic versioning + +Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in +July 2005 and originally planned for Maven 2)! +As expected, it's no longer required to define the parent versions in each subproject when using the new model version +4.1.0. +This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new +versions even more. + +The following code snippet shows the parent and dependency definition without the version tag. + +```xml + +<project xmlns="http://maven.apache.org/POM/4.1.0"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://maven.apache.org/POM/4.1.0 http://maven.apache.org/xsd/maven-4.1.0.xsd";> + <modelVersion>4.1.0</modelVersion> + + <parent> + <groupId>my.parents.groupId</groupId> + <artifactId>my.parents.artifactId</artifactId> + </parent> + + <artifactId>myOwnSubprojectArtifactId</artifactId> + + <dependencies> + <dependency> + <groupId>the.dependent.subproject.groupId</groupId> + <artifactId>the.dependent.subproject.artifactId</artifactId> + </dependency> + </dependencies> +</project> +``` + +### Full support of CI-friendly variables + +Maven 3.5.0 introduced partial support for CI-friendly variables, like `${revision}`, in your POM files. +However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality. +Since Maven 4, no additional plugin is needed; full built-in support is provided. +You can now use variables as versions in your configuration. + +Example + +```xml + +<groupId>my.groupId</groupId> +<artifactId>my.artifactId</artifactId> +<version>${revision}</version> +``` + +You have to provide a value for this variable when starting the build, for example by using a `maven.config` file. +In CI pipelines it's commonly done using a parameter, for example `mvn verify -Drevision=4.0.1`. + +Maven maintainer Karl Heinz Marbaise shows a larger example in +his [article "Maven 4 - Part I - Easier Versions" (2024)][21]. + +### Reactor improvements and fixes + +Building a project with multiple subprojects can cause confusion in Maven 3. +When the build of subproject B, which requires subproject A, is failing for whatever reason, Maven 3 is telling +the user to fix the error and then resume the build with `--resume-from :<nameOfTheFailingSubproject>`. +But doing this instantly fails the build again, because the required subproject A couldn't be found (as it was not +rebuilt). +Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing +bug [MNG-6863][11] - which is finally fixed with Maven 4! + +**Recommendation: Do not use `mvn clean install`. +Instead, use `mvn verify` for your regular builds!** + +To improve usability when resuming a failed build, you can now use `--resume` or its short parameter `-r` to resume a +build from the subproject that last failed. +So you don't have to manually pass the name of the failed subproject as the starting point to resume from. +The reactor is now also aware of successfully built subprojects when the overall build failed and will skip rebuilding +those if you resume the build. +With Maven 4, it's also aware of subfolder builds [MNG-6118][12], which becomes pretty handy when you only want to +execute tools (for example Jetty) on/with certain subprojects, but not on every subproject. +See Maven maintainer Maarten Mulders's article ["What's New in Maven 4" (2020)][13] for a small example. + +### Further improvements + +Further improvements to subprojects will also improve daily work with them. +Thanks to [MNG-6754][14], all subprojects will now have consistent timestamps in their packaged archives, while in Maven +3, each subproject had a different one. +This should make it easier to identify the archives that belong together. +When using Maven 3, deploying a project with multiple subprojects could end up in a situation where successfully Review Comment: TLDR: I removed it, because nothing has changed. Long story: I was assuming this too, because I was sure that I did hear it multiple times in a talk/chat that this would be the case. But the truth is, that the default value for `deployAtEnd` is still `false` in Maven 4 branch of the deploy plugin (same for install plugin). It "just" got several improvements, but even those slightly before the first maven 4 release, so also available in Maven 3 version of the plugin. Thanks for pointing this out! -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: issues-unsubscr...@maven.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
