elharo commented on code in PR #598: URL: https://github.com/apache/maven-site/pull/598#discussion_r1915625974
########## content/markdown/whatsnewinmaven4.md: ########## @@ -0,0 +1,496 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +<head> + <title>What's new in Maven 4?</title> + <meta name="author" content="Matthias Bünger" /> +</head> + +# What's new in Maven 4? + +Maven is over 20 years old, and is one of the most used build tools in the Java world. +Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of +its [POM file][2] with Model version 4.0.0. + +The POM file fulfills two elementary needs. +On the one side, the POM holds all the information and configuration, which are only needed to build the artifact. Review Comment: On the on side --> First ########## content/markdown/whatsnewinmaven4.md: ########## @@ -0,0 +1,496 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +<head> + <title>What's new in Maven 4?</title> + <meta name="author" content="Matthias Bünger" /> +</head> + +# What's new in Maven 4? + +Maven is over 20 years old, and is one of the most used build tools in the Java world. +Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of +its [POM file][2] with Model version 4.0.0. + +The POM file fulfills two elementary needs. +On the one side, the POM holds all the information and configuration, which are only needed to build the artifact. +After the artifact was created, these build information are not relevant anymore. +On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use +the artifact, e.g. dependencies. Review Comment: delete ", e.g. dependencies" as it confuses the dependent with the dependencies ########## content/markdown/whatsnewinmaven4.md: ########## @@ -0,0 +1,496 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +<head> + <title>What's new in Maven 4?</title> + <meta name="author" content="Matthias Bünger" /> +</head> + +# What's new in Maven 4? + +Maven is over 20 years old, and is one of the most used build tools in the Java world. +Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of +its [POM file][2] with Model version 4.0.0. + +The POM file fulfills two elementary needs. +On the one side, the POM holds all the information and configuration, which are only needed to build the artifact. +After the artifact was created, these build information are not relevant anymore. +On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use +the artifact, e.g. dependencies. +These dependent projects, which "consume" an artifact (and its POM), are called the "consumers" (of an artifact). + +This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the +Maven Central repository, other build tools, and IDEs. +This results in the situation, that any change in the POM's schema forces each participant of the ecosystem to either Review Comment: situation, that --> situation that ########## content/markdown/whatsnewinmaven4.md: ########## @@ -0,0 +1,496 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +<head> + <title>What's new in Maven 4?</title> + <meta name="author" content="Matthias Bünger" /> +</head> + +# What's new in Maven 4? + +Maven is over 20 years old, and is one of the most used build tools in the Java world. +Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of +its [POM file][2] with Model version 4.0.0. + +The POM file fulfills two elementary needs. +On the one side, the POM holds all the information and configuration, which are only needed to build the artifact. +After the artifact was created, these build information are not relevant anymore. +On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use +the artifact, e.g. dependencies. +These dependent projects, which "consume" an artifact (and its POM), are called the "consumers" (of an artifact). + +This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the +Maven Central repository, other build tools, and IDEs. +This results in the situation, that any change in the POM's schema forces each participant of the ecosystem to either +adopt the change or drop support. +So Maven's POM file got cemented, not able to change. + +> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases, +> unable to implement improvements that we imagine will require seriously updating the POM schema…" +> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite> + +But Maven should be able to advance. +For this, one important thing that's needed is to separate the information needed for the build from those needed by the +consumers, but without breaking in the ecosystem. +Maven 4 will prepare for this and more. + +This article presents and explains major changes brought by Maven 4, grouped into several topics. + +## POM Changes + +### Build-POM and Consumer-POM + +As written in the introduction, Model version 4.0.0 is used not only by the build but also by consumers of the +artifact. +However, several parts of the POM are only necessary for the build while others, like the dependencies, are also +needed by the consumers. +Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM". +As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., applied plugins Review Comment: will contain --> contains It's likely this doc exists in the same time frame as Maven 4 so use present tense when describing it ########## content/markdown/whatsnewinmaven4.md: ########## @@ -0,0 +1,474 @@ +# What's New in Maven 4? + +Maven is over 20 years old and is one of the most used build tools in the Java world. +Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially +with its [POM-schema with Model version 4.0.0][2], used not only for the build itself but also by consumers. +This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the Maven +Central repository, other build tools, and IDEs. +But this stable schema comes at a price - the lack of flexibility. + +> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases, +> unable to implement improvements that we imagine will require seriously updating the POM schema…" +> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite> + +Maven 4 will prepare for changes which are impossible nowadays, like a completely new build schema. + +Another pain point of Maven 3 is a codebase with a lot of deprecated, convoluted, non-performant, and duplicated code +which costs the volunteers who maintain Maven a lot of time. +This not only means that the Maven codebase contains old Java code that can be optimized nowadays but also old +dependencies and poor API design of its own APIs, especially for Maven plugins. +Therefore, Maven 4 will also be a maintenance release. + +This article presents and explains major changes brought by Maven 4, grouped into several topics. + +## POM Changes + +### Build-POM and Consumer-POM + +As written in the introduction, Model version 4.0.0 is used not only for the build but also by consumers of the +artifact. +However, several contents of the POM are only necessary for the build while others, like the dependencies, are also +needed by the consumer. +Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM". +As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., used plugins and +their configuration, while the "Consumer-POM", which is created during the Maven build, will not contain those. +This POM will only keep what is really needed to use the artifact, e.g., dependency information. + +**Note**: See below for a comparison of the content of both POMs. + +### Model version 4.1.0 + +With now having two types of POM, Maven 4 can already make additions to the Build-POM as it will only be used by Maven ( +and of course IDEs). +Therefore, with Maven 4, a new Model version 4.1.0 is introduced. +This version introduces some new elements and attributes, while others are marked as deprecated. +To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use +version 4.0.0. +This means Maven will generate the Consumer-POM during the build. + +**Note**: Maven 4 will of course continue to build your model version 4.0.0 project! +There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features. +But as with every software update - it's suggested to update them to 4.1.0, e.g., to avoid problems when deprecated +features are removed in future updates. + +### Modules are now subprojects + +From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object +Model". +Together with build folders and other files, the wording "Maven project" is used. +However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module" +and listed in the `<modules>` section of the POM, leading to the terms "multi-module project". +This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called " +single-module". +Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional +confusion. + +Maven 4 gets rid of this by naming "modules" as what they are - subprojects. +Model version 4.1.0 contains a new element `<subprojects>` analogous to the now deprecated, but still usable, element +`<modules>`. + +**Note**: It's suggested to use the terms `multi-project setup` and `single-project setup` to differentiate between a +Maven project with or without subprojects. + +### New packaging type: bom + +Maven 4 introduces a dedicated packaging type to provide a [Bill of Material BOM][4] called "bom" to differentiate more +precisely between "parent POMs" and dependency-managing BOMs. +While the new type is only available with Model Version 4.1.0, the final outcome is a full Maven 3 compatible (model +4.0.0) POM file! +For an example, see the link above or +the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5]. + +**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing +`<exclusions>` element. +Also note that in Maven 4, importing BOMs with a classifier is now possible. +Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the +`<bomClassifier>` element. +This means that an imported BOM must **not** come from the same reactor as the current build but be available outside +the project before the build (in other words, "you should import only external BOMs") or it may break your build (as +shown in [MNG-8009][32]). +That's why Maven 4.0 will show a warning if a BOM comes from the same reactor. +In the future, this will most probably be changed to make the build fail. + +### Comparing Build-POM and Consumer-POM + +The following table shows a rough comparison of which content is available in which POM type when using Maven 4. + +**Notes**: + +* The column "Consumer-POM" obviously does not apply to artifacts that are of type "pom"! +* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in + the Build-POM in the future. + +| Content | Build-POM | Consumer-POM | +|:-------------------------------------------|:---------:|:------------:| +| Model version | 4.1.0 | 4.0.0 | +| 3rd party dependency information | ✅ | ✅ | +| Properties | ✅ | ❌ | Review Comment: Are these Java system properties? ########## content/markdown/whatsnewinmaven4.md: ########## @@ -0,0 +1,496 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +<head> + <title>What's new in Maven 4?</title> + <meta name="author" content="Matthias Bünger" /> +</head> + +# What's new in Maven 4? + +Maven is over 20 years old, and is one of the most used build tools in the Java world. +Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of +its [POM file][2] with Model version 4.0.0. + +The POM file fulfills two elementary needs. +On the one side, the POM holds all the information and configuration, which are only needed to build the artifact. +After the artifact was created, these build information are not relevant anymore. +On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use +the artifact, e.g. dependencies. +These dependent projects, which "consume" an artifact (and its POM), are called the "consumers" (of an artifact). + +This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the +Maven Central repository, other build tools, and IDEs. +This results in the situation, that any change in the POM's schema forces each participant of the ecosystem to either +adopt the change or drop support. +So Maven's POM file got cemented, not able to change. + +> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases, +> unable to implement improvements that we imagine will require seriously updating the POM schema…" +> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite> + +But Maven should be able to advance. +For this, one important thing that's needed is to separate the information needed for the build from those needed by the +consumers, but without breaking in the ecosystem. +Maven 4 will prepare for this and more. + +This article presents and explains major changes brought by Maven 4, grouped into several topics. + +## POM Changes + +### Build-POM and Consumer-POM + +As written in the introduction, Model version 4.0.0 is used not only by the build but also by consumers of the +artifact. +However, several parts of the POM are only necessary for the build while others, like the dependencies, are also +needed by the consumers. +Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM". +As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., applied plugins +and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is +necessary. +This POM will only keep what is really needed to use the artifact, e.g., dependency information. + +**Note**: See below for a comparison of the content of both POMs. + +### Model version 4.1.0 + +With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven. +Therefore, with Maven 4, a new Model version 4.1.0 is introduced. +This version adds some new elements and attributes, while others are marked as deprecated. +To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use +version 4.0.0. +Maven generates the Consumer-POM during the build from the build POM. + +**Note**: Maven 4 will continue to build your model version 4.0.0 project. +There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features. + +### Modules are now subprojects + +From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object +Model". +Together with build folders and other files, the wording "Maven project" is used. +However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module" +and listed in the `<modules>` section of the POM, leading to the terms "multi-module project". +This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called " +single-module". +Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional +confusion. + +Maven 4 gets rid of this by naming "modules" as what they are - subprojects. +Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable, +`<modules>` element. + +**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with +or without subprojects. + +### New packaging type: bom + +Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more +precisely between "parent POMs" and dependency-managing BOMs. +The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3 +compatible Consumer-POM during the build. +For an example, see the link above or +the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5]. + +**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing +`<exclusions>` element. +Also note that in Maven 4, importing BOMs with a classifier is now possible. +Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the +`<bomClassifier>` element. +This means that an imported BOM must **not** come from the same reactor as the current build but be available outside +the project before the build (in other words: you should import only external BOMs). +That's why Maven 4.0 will show a warning if a BOM comes from the same reactor. +In the future, this will most probably be changed to make the build fail. + +### Comparing Build-POM and Consumer-POM + +The following table shows a rough comparison of which content is available in which POM type when using Maven 4. + +**Notes**: + +* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to + contain build information, e.g. plugin configuration! +* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in + the Build-POM in the future. + +| Content | Build-POM | Consumer-POM | +|:-------------------------------------------|:---------:|:------------:| +| Model version | 4.1.0 | 4.0.0 | +| 3rd party dependency information | ✅ | ✅ | +| Properties | ✅ | ❌ | +| Plugin configuration | ✅ | ❌ | +| Repository information | ✅ | ✅ | +| Project information / environment settings | ✅ | ✅ | +| Deployment to remote repository | ✅ | ✅ | + +**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when +condition-based profiles (see below) can't be transformed to version 4.0.0. +Maven will show a warning in such situations. + +### Declaring the root directory and directory properties + +Every time Maven executes a build, it has to determine the project's root to identify things like the parent project, +directory information, and so on. +To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory. +This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config` +file, and therefore was also considered as the root folder. +With Maven 4, there is a second option to clearly define the root folder. +Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element. +When this attribute is set to true (default is false), the directory of this POM file is considered the root directory. + +Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use +of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for +the checkstyle plugin. +Maven 4 now provides official properties to reference the root directory in your POM configuration. +The following table shows the official properties. + +| Property | Scope | Definition | Always | +|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:| +| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No | +| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes | +| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No | + +As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's +definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the +directory from where you start Maven. +As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn` +directory is defined or the `root` attribute is set to true. +However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory` +property can change depending on the execution point. + +Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each +subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM +files and will always have a value. + +**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal +properties. +Starting with Maven 4, those "hacks" will most probably not work anymore because some of those properties were removed +or at least marked as deprecated. +See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information. + +### Alternate POM syntaxes + +While the syntax for the 4.0.0 Consumer-POM is set in stone, the Build-POM should be able to evolve. +This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]), +which can be implemented as a core extension and allow a custom syntax. + +One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25]. + +## Improvements for subprojects + +### Automatic versioning + +Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in +July 2005 and originally planned for Maven 2)! +As expected, it's no longer required to define the parent versions in each subproject when using the new model version +4.1.0. +This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new +versions even more. + +The following code snippet shows the parent and dependency definition without the version tag. + +```xml + +<project xmlns="http://maven.apache.org/POM/4.1.0"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://maven.apache.org/POM/4.1.0 http://maven.apache.org/xsd/maven-4.1.0.xsd";> + <modelVersion>4.1.0</modelVersion> + + <parent> + <groupId>my.parents.groupId</groupId> + <artifactId>my.parents.artifactId</artifactId> + </parent> + + <artifactId>myOwnSubprojectArtifactId</artifactId> + + <dependencies> + <dependency> + <groupId>the.dependent.subproject.groupId</groupId> + <artifactId>the.dependent.subproject.artifactId</artifactId> + </dependency> + </dependencies> +</project> +``` + +### Full support of CI-friendly variables + +Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files. +However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality. +Since Maven 4, no additional plugin is needed; full built-in support is provided. +You can now use variables as versions in your configuration, e.g., + +```xml + +<groupId>my.groupId</groupId> +<artifactId>my.artifactId</artifactId> +<version>${revision}</version> +``` + +You have to provide a value for this variable when starting the build, for example by using a `maven.config` file. +In CI pipelines it's commonly done using a parameter, e.g., `mvn verify -Drevision=4.0.1`. + +Maven maintainer Karl Heinz Marbaise shows a larger example in +his [article "Maven 4 - Part I - Easier Versions" (2024)][21]. + +### Reactor improvements and fixes + +Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the +others and its own build failed for whatever reason. +Maven was telling the user to (fix the error and then) resume the build with +`--resume-from :<nameOfTheFailingSubproject>`, which instantly fails the build again as the needed other subproject +couldn't be found (as it was not rebuilt). +Using `--also-make :<nameOfTheDependentSubproject>` was no help in the past as it was ignored due to the long-standing +bug [MNG-6863][11] - which is finally fixed with Maven 4! + +**Recommendation: Do not use `mvn clean install`, but `mvn verify` for your regular builds!** Review Comment: , but --> . Instead ########## content/markdown/whatsnewinmaven4.md: ########## @@ -0,0 +1,496 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +<head> + <title>What's new in Maven 4?</title> + <meta name="author" content="Matthias Bünger" /> +</head> + +# What's new in Maven 4? + +Maven is over 20 years old, and is one of the most used build tools in the Java world. +Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of +its [POM file][2] with Model version 4.0.0. + +The POM file fulfills two elementary needs. +On the one side, the POM holds all the information and configuration, which are only needed to build the artifact. +After the artifact was created, these build information are not relevant anymore. +On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use +the artifact, e.g. dependencies. +These dependent projects, which "consume" an artifact (and its POM), are called the "consumers" (of an artifact). Review Comment: delete "which "consume" an artifact (and its POM)," ########## content/markdown/whatsnewinmaven4.md: ########## @@ -0,0 +1,496 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +<head> + <title>What's new in Maven 4?</title> + <meta name="author" content="Matthias Bünger" /> +</head> + +# What's new in Maven 4? + +Maven is over 20 years old, and is one of the most used build tools in the Java world. +Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of +its [POM file][2] with Model version 4.0.0. + +The POM file fulfills two elementary needs. +On the one side, the POM holds all the information and configuration, which are only needed to build the artifact. +After the artifact was created, these build information are not relevant anymore. +On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use +the artifact, e.g. dependencies. +These dependent projects, which "consume" an artifact (and its POM), are called the "consumers" (of an artifact). + +This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the +Maven Central repository, other build tools, and IDEs. +This results in the situation, that any change in the POM's schema forces each participant of the ecosystem to either +adopt the change or drop support. +So Maven's POM file got cemented, not able to change. + +> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases, +> unable to implement improvements that we imagine will require seriously updating the POM schema…" +> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite> + +But Maven should be able to advance. +For this, one important thing that's needed is to separate the information needed for the build from those needed by the +consumers, but without breaking in the ecosystem. Review Comment: in the --> the ########## content/markdown/whatsnewinmaven4.md: ########## @@ -0,0 +1,496 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +<head> + <title>What's new in Maven 4?</title> + <meta name="author" content="Matthias Bünger" /> +</head> + +# What's new in Maven 4? + +Maven is over 20 years old, and is one of the most used build tools in the Java world. +Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of +its [POM file][2] with Model version 4.0.0. + +The POM file fulfills two elementary needs. +On the one side, the POM holds all the information and configuration, which are only needed to build the artifact. +After the artifact was created, these build information are not relevant anymore. Review Comment: After the artifact is created, this build information is not relevant anymore. ########## content/markdown/whatsnewinmaven4.md: ########## @@ -0,0 +1,496 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +<head> + <title>What's new in Maven 4?</title> + <meta name="author" content="Matthias Bünger" /> +</head> + +# What's new in Maven 4? + +Maven is over 20 years old, and is one of the most used build tools in the Java world. +Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of +its [POM file][2] with Model version 4.0.0. + +The POM file fulfills two elementary needs. +On the one side, the POM holds all the information and configuration, which are only needed to build the artifact. +After the artifact was created, these build information are not relevant anymore. +On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use Review Comment: On then other side --> Second no comma after projects ########## content/markdown/whatsnewinmaven4.md: ########## @@ -0,0 +1,496 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +<head> + <title>What's new in Maven 4?</title> + <meta name="author" content="Matthias Bünger" /> +</head> + +# What's new in Maven 4? + +Maven is over 20 years old, and is one of the most used build tools in the Java world. +Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of +its [POM file][2] with Model version 4.0.0. + +The POM file fulfills two elementary needs. +On the one side, the POM holds all the information and configuration, which are only needed to build the artifact. +After the artifact was created, these build information are not relevant anymore. +On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use +the artifact, e.g. dependencies. +These dependent projects, which "consume" an artifact (and its POM), are called the "consumers" (of an artifact). + +This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the +Maven Central repository, other build tools, and IDEs. +This results in the situation, that any change in the POM's schema forces each participant of the ecosystem to either +adopt the change or drop support. +So Maven's POM file got cemented, not able to change. Review Comment: Thus the Maven POM syntax became fixed, unable to change. ########## content/markdown/whatsnewinmaven4.md: ########## @@ -0,0 +1,496 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +<head> + <title>What's new in Maven 4?</title> + <meta name="author" content="Matthias Bünger" /> +</head> + +# What's new in Maven 4? + +Maven is over 20 years old, and is one of the most used build tools in the Java world. +Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of +its [POM file][2] with Model version 4.0.0. + +The POM file fulfills two elementary needs. +On the one side, the POM holds all the information and configuration, which are only needed to build the artifact. +After the artifact was created, these build information are not relevant anymore. +On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use +the artifact, e.g. dependencies. +These dependent projects, which "consume" an artifact (and its POM), are called the "consumers" (of an artifact). + +This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the +Maven Central repository, other build tools, and IDEs. +This results in the situation, that any change in the POM's schema forces each participant of the ecosystem to either +adopt the change or drop support. +So Maven's POM file got cemented, not able to change. + +> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases, +> unable to implement improvements that we imagine will require seriously updating the POM schema…" +> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite> + +But Maven should be able to advance. +For this, one important thing that's needed is to separate the information needed for the build from those needed by the +consumers, but without breaking in the ecosystem. +Maven 4 will prepare for this and more. Review Comment: will prepare --> prepares ########## content/markdown/whatsnewinmaven4.md: ########## @@ -0,0 +1,496 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +<head> + <title>What's new in Maven 4?</title> + <meta name="author" content="Matthias Bünger" /> +</head> + +# What's new in Maven 4? + +Maven is over 20 years old, and is one of the most used build tools in the Java world. +Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of +its [POM file][2] with Model version 4.0.0. + +The POM file fulfills two elementary needs. +On the one side, the POM holds all the information and configuration, which are only needed to build the artifact. +After the artifact was created, these build information are not relevant anymore. +On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use +the artifact, e.g. dependencies. +These dependent projects, which "consume" an artifact (and its POM), are called the "consumers" (of an artifact). + +This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the +Maven Central repository, other build tools, and IDEs. +This results in the situation, that any change in the POM's schema forces each participant of the ecosystem to either +adopt the change or drop support. +So Maven's POM file got cemented, not able to change. + +> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases, +> unable to implement improvements that we imagine will require seriously updating the POM schema…" +> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite> + +But Maven should be able to advance. +For this, one important thing that's needed is to separate the information needed for the build from those needed by the +consumers, but without breaking in the ecosystem. +Maven 4 will prepare for this and more. + +This article presents and explains major changes brought by Maven 4, grouped into several topics. + +## POM Changes + +### Build-POM and Consumer-POM + +As written in the introduction, Model version 4.0.0 is used not only by the build but also by consumers of the +artifact. +However, several parts of the POM are only necessary for the build while others, like the dependencies, are also +needed by the consumers. +Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM". +As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., applied plugins +and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is +necessary. +This POM will only keep what is really needed to use the artifact, e.g., dependency information. + +**Note**: See below for a comparison of the content of both POMs. + +### Model version 4.1.0 + +With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven. +Therefore, with Maven 4, a new Model version 4.1.0 is introduced. +This version adds some new elements and attributes, while others are marked as deprecated. +To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use +version 4.0.0. +Maven generates the Consumer-POM during the build from the build POM. + +**Note**: Maven 4 will continue to build your model version 4.0.0 project. +There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features. + +### Modules are now subprojects + +From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object +Model". +Together with build folders and other files, the wording "Maven project" is used. +However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module" +and listed in the `<modules>` section of the POM, leading to the terms "multi-module project". +This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called " +single-module". +Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional +confusion. + +Maven 4 gets rid of this by naming "modules" as what they are - subprojects. +Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable, +`<modules>` element. + +**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with +or without subprojects. + +### New packaging type: bom + +Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more +precisely between "parent POMs" and dependency-managing BOMs. +The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3 +compatible Consumer-POM during the build. +For an example, see the link above or +the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5]. + +**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing +`<exclusions>` element. +Also note that in Maven 4, importing BOMs with a classifier is now possible. +Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the +`<bomClassifier>` element. +This means that an imported BOM must **not** come from the same reactor as the current build but be available outside +the project before the build (in other words: you should import only external BOMs). +That's why Maven 4.0 will show a warning if a BOM comes from the same reactor. +In the future, this will most probably be changed to make the build fail. + +### Comparing Build-POM and Consumer-POM + +The following table shows a rough comparison of which content is available in which POM type when using Maven 4. + +**Notes**: + +* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to + contain build information, e.g. plugin configuration! +* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in + the Build-POM in the future. + +| Content | Build-POM | Consumer-POM | +|:-------------------------------------------|:---------:|:------------:| +| Model version | 4.1.0 | 4.0.0 | +| 3rd party dependency information | ✅ | ✅ | +| Properties | ✅ | ❌ | +| Plugin configuration | ✅ | ❌ | +| Repository information | ✅ | ✅ | +| Project information / environment settings | ✅ | ✅ | +| Deployment to remote repository | ✅ | ✅ | + +**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when +condition-based profiles (see below) can't be transformed to version 4.0.0. +Maven will show a warning in such situations. + +### Declaring the root directory and directory properties + +Every time Maven executes a build, it has to determine the project's root to identify things like the parent project, +directory information, and so on. +To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory. +This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config` +file, and therefore was also considered as the root folder. +With Maven 4, there is a second option to clearly define the root folder. +Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element. +When this attribute is set to true (default is false), the directory of this POM file is considered the root directory. + +Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use +of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for +the checkstyle plugin. +Maven 4 now provides official properties to reference the root directory in your POM configuration. +The following table shows the official properties. + +| Property | Scope | Definition | Always | +|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:| +| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No | +| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes | +| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No | + +As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's +definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the +directory from where you start Maven. +As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn` +directory is defined or the `root` attribute is set to true. +However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory` +property can change depending on the execution point. + +Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each +subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM +files and will always have a value. + +**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal +properties. +Starting with Maven 4, those "hacks" will most probably not work anymore because some of those properties were removed +or at least marked as deprecated. +See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information. + +### Alternate POM syntaxes + +While the syntax for the 4.0.0 Consumer-POM is set in stone, the Build-POM should be able to evolve. +This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]), +which can be implemented as a core extension and allow a custom syntax. + +One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25]. + +## Improvements for subprojects + +### Automatic versioning + +Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in +July 2005 and originally planned for Maven 2)! +As expected, it's no longer required to define the parent versions in each subproject when using the new model version +4.1.0. +This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new +versions even more. + +The following code snippet shows the parent and dependency definition without the version tag. + +```xml + +<project xmlns="http://maven.apache.org/POM/4.1.0"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://maven.apache.org/POM/4.1.0 http://maven.apache.org/xsd/maven-4.1.0.xsd";> + <modelVersion>4.1.0</modelVersion> + + <parent> + <groupId>my.parents.groupId</groupId> + <artifactId>my.parents.artifactId</artifactId> + </parent> + + <artifactId>myOwnSubprojectArtifactId</artifactId> + + <dependencies> + <dependency> + <groupId>the.dependent.subproject.groupId</groupId> + <artifactId>the.dependent.subproject.artifactId</artifactId> + </dependency> + </dependencies> +</project> +``` + +### Full support of CI-friendly variables + +Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files. +However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality. +Since Maven 4, no additional plugin is needed; full built-in support is provided. +You can now use variables as versions in your configuration, e.g., + +```xml + +<groupId>my.groupId</groupId> +<artifactId>my.artifactId</artifactId> +<version>${revision}</version> +``` + +You have to provide a value for this variable when starting the build, for example by using a `maven.config` file. +In CI pipelines it's commonly done using a parameter, e.g., `mvn verify -Drevision=4.0.1`. + +Maven maintainer Karl Heinz Marbaise shows a larger example in +his [article "Maven 4 - Part I - Easier Versions" (2024)][21]. + +### Reactor improvements and fixes + +Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the Review Comment: was dependent --> depended ########## content/markdown/whatsnewinmaven4.md: ########## @@ -0,0 +1,496 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +<head> + <title>What's new in Maven 4?</title> + <meta name="author" content="Matthias Bünger" /> +</head> + +# What's new in Maven 4? + +Maven is over 20 years old, and is one of the most used build tools in the Java world. +Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of +its [POM file][2] with Model version 4.0.0. + +The POM file fulfills two elementary needs. +On the one side, the POM holds all the information and configuration, which are only needed to build the artifact. +After the artifact was created, these build information are not relevant anymore. +On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use +the artifact, e.g. dependencies. +These dependent projects, which "consume" an artifact (and its POM), are called the "consumers" (of an artifact). + +This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the +Maven Central repository, other build tools, and IDEs. +This results in the situation, that any change in the POM's schema forces each participant of the ecosystem to either +adopt the change or drop support. +So Maven's POM file got cemented, not able to change. + +> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases, +> unable to implement improvements that we imagine will require seriously updating the POM schema…" +> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite> + +But Maven should be able to advance. +For this, one important thing that's needed is to separate the information needed for the build from those needed by the +consumers, but without breaking in the ecosystem. +Maven 4 will prepare for this and more. + +This article presents and explains major changes brought by Maven 4, grouped into several topics. + +## POM Changes + +### Build-POM and Consumer-POM + +As written in the introduction, Model version 4.0.0 is used not only by the build but also by consumers of the Review Comment: Delete "As written in the introduction, " It's important to note that model version 4.0.0 is what's used by Maven 3 and model version 4.1 is used by Maven 4 since this is surprising. ########## content/markdown/whatsnewinmaven4.md: ########## @@ -0,0 +1,496 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +<head> + <title>What's new in Maven 4?</title> + <meta name="author" content="Matthias Bünger" /> +</head> + +# What's new in Maven 4? + +Maven is over 20 years old, and is one of the most used build tools in the Java world. +Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of +its [POM file][2] with Model version 4.0.0. + +The POM file fulfills two elementary needs. +On the one side, the POM holds all the information and configuration, which are only needed to build the artifact. +After the artifact was created, these build information are not relevant anymore. +On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use +the artifact, e.g. dependencies. +These dependent projects, which "consume" an artifact (and its POM), are called the "consumers" (of an artifact). + +This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the +Maven Central repository, other build tools, and IDEs. +This results in the situation, that any change in the POM's schema forces each participant of the ecosystem to either +adopt the change or drop support. +So Maven's POM file got cemented, not able to change. + +> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases, +> unable to implement improvements that we imagine will require seriously updating the POM schema…" +> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite> + +But Maven should be able to advance. +For this, one important thing that's needed is to separate the information needed for the build from those needed by the Review Comment: those --> the information ########## content/markdown/whatsnewinmaven4.md: ########## @@ -0,0 +1,496 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +<head> + <title>What's new in Maven 4?</title> + <meta name="author" content="Matthias Bünger" /> +</head> + +# What's new in Maven 4? + +Maven is over 20 years old, and is one of the most used build tools in the Java world. +Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of +its [POM file][2] with Model version 4.0.0. + +The POM file fulfills two elementary needs. +On the one side, the POM holds all the information and configuration, which are only needed to build the artifact. +After the artifact was created, these build information are not relevant anymore. +On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use +the artifact, e.g. dependencies. +These dependent projects, which "consume" an artifact (and its POM), are called the "consumers" (of an artifact). + +This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the +Maven Central repository, other build tools, and IDEs. +This results in the situation, that any change in the POM's schema forces each participant of the ecosystem to either +adopt the change or drop support. +So Maven's POM file got cemented, not able to change. + +> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases, +> unable to implement improvements that we imagine will require seriously updating the POM schema…" +> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite> + +But Maven should be able to advance. +For this, one important thing that's needed is to separate the information needed for the build from those needed by the +consumers, but without breaking in the ecosystem. +Maven 4 will prepare for this and more. + +This article presents and explains major changes brought by Maven 4, grouped into several topics. + +## POM Changes + +### Build-POM and Consumer-POM + +As written in the introduction, Model version 4.0.0 is used not only by the build but also by consumers of the +artifact. +However, several parts of the POM are only necessary for the build while others, like the dependencies, are also +needed by the consumers. +Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM". +As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., applied plugins +and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is +necessary. Review Comment: necassary for ???? ########## content/markdown/whatsnewinmaven4.md: ########## @@ -0,0 +1,496 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +<head> + <title>What's new in Maven 4?</title> + <meta name="author" content="Matthias Bünger" /> +</head> + +# What's new in Maven 4? + +Maven is over 20 years old, and is one of the most used build tools in the Java world. +Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of +its [POM file][2] with Model version 4.0.0. + +The POM file fulfills two elementary needs. +On the one side, the POM holds all the information and configuration, which are only needed to build the artifact. +After the artifact was created, these build information are not relevant anymore. +On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use +the artifact, e.g. dependencies. +These dependent projects, which "consume" an artifact (and its POM), are called the "consumers" (of an artifact). + +This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the +Maven Central repository, other build tools, and IDEs. +This results in the situation, that any change in the POM's schema forces each participant of the ecosystem to either +adopt the change or drop support. +So Maven's POM file got cemented, not able to change. + +> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases, +> unable to implement improvements that we imagine will require seriously updating the POM schema…" +> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite> + +But Maven should be able to advance. +For this, one important thing that's needed is to separate the information needed for the build from those needed by the +consumers, but without breaking in the ecosystem. +Maven 4 will prepare for this and more. + +This article presents and explains major changes brought by Maven 4, grouped into several topics. + +## POM Changes + +### Build-POM and Consumer-POM + +As written in the introduction, Model version 4.0.0 is used not only by the build but also by consumers of the +artifact. +However, several parts of the POM are only necessary for the build while others, like the dependencies, are also +needed by the consumers. +Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM". Review Comment: will therefore differentiate --> therefore differentiates ########## content/markdown/whatsnewinmaven4.md: ########## @@ -0,0 +1,496 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +<head> + <title>What's new in Maven 4?</title> + <meta name="author" content="Matthias Bünger" /> +</head> + +# What's new in Maven 4? + +Maven is over 20 years old, and is one of the most used build tools in the Java world. +Throughout the years, one important rule has been maintaining the highest backward compatibility possible, especially of +its [POM file][2] with Model version 4.0.0. + +The POM file fulfills two elementary needs. +On the one side, the POM holds all the information and configuration, which are only needed to build the artifact. +After the artifact was created, these build information are not relevant anymore. +On the other side, the POM also contains information, e.g. dependencies, which are needed by projects, which want to use +the artifact, e.g. dependencies. +These dependent projects, which "consume" an artifact (and its POM), are called the "consumers" (of an artifact). + +This made the Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the +Maven Central repository, other build tools, and IDEs. +This results in the situation, that any change in the POM's schema forces each participant of the ecosystem to either +adopt the change or drop support. +So Maven's POM file got cemented, not able to change. + +> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases, +> unable to implement improvements that we imagine will require seriously updating the POM schema…" +> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite> + +But Maven should be able to advance. +For this, one important thing that's needed is to separate the information needed for the build from those needed by the +consumers, but without breaking in the ecosystem. +Maven 4 will prepare for this and more. + +This article presents and explains major changes brought by Maven 4, grouped into several topics. + +## POM Changes + +### Build-POM and Consumer-POM + +As written in the introduction, Model version 4.0.0 is used not only by the build but also by consumers of the +artifact. +However, several parts of the POM are only necessary for the build while others, like the dependencies, are also +needed by the consumers. +Maven 4 will therefore differentiate between a "Build-POM" and a "Consumer-POM". +As the names suggest, the "Build-POM" will contain all information needed to build the artifact, e.g., applied plugins +and their configuration, while the "Consumer-POM", which is created during the Maven build, only contains what is +necessary. +This POM will only keep what is really needed to use the artifact, e.g., dependency information. + +**Note**: See below for a comparison of the content of both POMs. + +### Model version 4.1.0 + +With two types of POM, Maven 4 can make additions to the Build-POM as it is only be used by Maven. +Therefore, with Maven 4, a new Model version 4.1.0 is introduced. +This version adds some new elements and attributes, while others are marked as deprecated. +To not break the ecosystem, this version is only available for the Build-POM, while the Consumer-POM will still use +version 4.0.0. +Maven generates the Consumer-POM during the build from the build POM. + +**Note**: Maven 4 will continue to build your model version 4.0.0 project. +There is no need to update your POMs to 4.1.0 as long as you don't want to make use of the new features. + +### Modules are now subprojects + +From the early days of Maven 1 until today, all build information is stored in the POM, short for "Project Object +Model". +Together with build folders and other files, the wording "Maven project" is used. +However, for projects containing multiple parts, e.g., an API and a client, each of those parts was called a "module" +and listed in the `<modules>` section of the POM, leading to the terms "multi-module project". +This wording introduced some inconsistency, especially as projects without any `<modules>` section are often called " +single-module". +Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional +confusion. + +Maven 4 gets rid of this by naming "modules" as what they are - subprojects. +Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable, +`<modules>` element. + +**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with +or without subprojects. + +### New packaging type: bom + +Maven 4 introduces a dedicated packaging type to provide a [Bill of Materials BOM][4] called "bom" to differentiate more +precisely between "parent POMs" and dependency-managing BOMs. +The new type is only available as a Build-POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3 +compatible Consumer-POM during the build. +For an example, see the link above or +the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5]. + +**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing +`<exclusions>` element. +Also note that in Maven 4, importing BOMs with a classifier is now possible. +Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the +`<bomClassifier>` element. +This means that an imported BOM must **not** come from the same reactor as the current build but be available outside +the project before the build (in other words: you should import only external BOMs). +That's why Maven 4.0 will show a warning if a BOM comes from the same reactor. +In the future, this will most probably be changed to make the build fail. + +### Comparing Build-POM and Consumer-POM + +The following table shows a rough comparison of which content is available in which POM type when using Maven 4. + +**Notes**: + +* The column "Consumer-POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to + contain build information, e.g. plugin configuration! +* Some of the build-related content which is (as of now) still available in the Consumer-POM might be available only in + the Build-POM in the future. + +| Content | Build-POM | Consumer-POM | +|:-------------------------------------------|:---------:|:------------:| +| Model version | 4.1.0 | 4.0.0 | +| 3rd party dependency information | ✅ | ✅ | +| Properties | ✅ | ❌ | +| Plugin configuration | ✅ | ❌ | +| Repository information | ✅ | ✅ | +| Project information / environment settings | ✅ | ✅ | +| Deployment to remote repository | ✅ | ✅ | + +**Warning**: There are rare situations where Maven 4 will produce a Consumer-POM based on version 4.1.0, e.g., when +condition-based profiles (see below) can't be transformed to version 4.0.0. +Maven will show a warning in such situations. + +### Declaring the root directory and directory properties + +Every time Maven executes a build, it has to determine the project's root to identify things like the parent project, +directory information, and so on. +To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory. +This folder is intended to contain project-specific configuration to run Maven, e.g., a `maven.config` or `jvm.config` +file, and therefore was also considered as the root folder. +With Maven 4, there is a second option to clearly define the root folder. +Model version 4.1.0, usable for the Build-POM, adds a boolean attribute called `root` in the `<project>` element. +When this attribute is set to true (default is false), the directory of this POM file is considered the root directory. + +Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use +of the root folder in your POM files, e.g., when you want to define the path to a `checkstyle-suppressions.xml` file for +the checkstyle plugin. +Maven 4 now provides official properties to reference the root directory in your POM configuration. +The following table shows the official properties. + +| Property | Scope | Definition | Always | +|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:| +| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No | +| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes | +| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No | + +As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's +definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the +directory from where you start Maven. +As a consequence of the definition, it's clear that the `rootDirectory` can only contain a value when either a `.mvn` +directory is defined or the `root` attribute is set to true. +However, if defined, it should always have the same value for a given project, whereas the value of the `topDirectory` +property can change depending on the execution point. + +Keep in mind that the root directory of the whole project (when considering multiple subprojects) is different from each +subproject's own base directory, which is still accessible via the `${basedir}` property for use in POM +files and will always have a value. + +**Note:** In the past, some people "hacked" workarounds for the `rootDirectory` properties, mostly by using internal +properties. +Starting with Maven 4, those "hacks" will most probably not work anymore because some of those properties were removed +or at least marked as deprecated. +See JIRA issue [MNG-7038][15] and the related [Pull Request for MNG-7038][16] for more information. + +### Alternate POM syntaxes + +While the syntax for the 4.0.0 Consumer-POM is set in stone, the Build-POM should be able to evolve. +This includes allowing the use of alternate syntaxes by having Maven 4 provide a ModelParser SPI ([MNG-7836][24]), +which can be implemented as a core extension and allow a custom syntax. + +One of the first projects that uses this feature is the [Apache Maven Hocon Extension][25]. + +## Improvements for subprojects + +### Automatic versioning + +Maven 4 finally ships one of the oldest improvement requests - automatic parent versioning ([MNG-624][17], created in +July 2005 and originally planned for Maven 2)! +As expected, it's no longer required to define the parent versions in each subproject when using the new model version +4.1.0. +This also extends to dependencies of project's own subprojects and reduces the need to update POM files for new +versions even more. + +The following code snippet shows the parent and dependency definition without the version tag. + +```xml + +<project xmlns="http://maven.apache.org/POM/4.1.0"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://maven.apache.org/POM/4.1.0 http://maven.apache.org/xsd/maven-4.1.0.xsd";> + <modelVersion>4.1.0</modelVersion> + + <parent> + <groupId>my.parents.groupId</groupId> + <artifactId>my.parents.artifactId</artifactId> + </parent> + + <artifactId>myOwnSubprojectArtifactId</artifactId> + + <dependencies> + <dependency> + <groupId>the.dependent.subproject.groupId</groupId> + <artifactId>the.dependent.subproject.artifactId</artifactId> + </dependency> + </dependencies> +</project> +``` + +### Full support of CI-friendly variables + +Maven 3.5.0 introduced partial support for CI-friendly variables, e.g., `${revision}`, in your POM files. +However, this still required the usage of the [Flatten Maven Plugin][20] for full functionality. +Since Maven 4, no additional plugin is needed; full built-in support is provided. +You can now use variables as versions in your configuration, e.g., + +```xml + +<groupId>my.groupId</groupId> +<artifactId>my.artifactId</artifactId> +<version>${revision}</version> +``` + +You have to provide a value for this variable when starting the build, for example by using a `maven.config` file. +In CI pipelines it's commonly done using a parameter, e.g., `mvn verify -Drevision=4.0.1`. + +Maven maintainer Karl Heinz Marbaise shows a larger example in +his [article "Maven 4 - Part I - Easier Versions" (2024)][21]. + +### Reactor improvements and fixes + +Building a project with multiple subprojects could cause trouble when one subproject was dependent on one of the +others and its own build failed for whatever reason. +Maven was telling the user to (fix the error and then) resume the build with Review Comment: no parentheses -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: issues-unsubscr...@maven.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
