Bukama commented on code in PR #598: URL: https://github.com/apache/maven-site/pull/598#discussion_r1927468031
########## content/markdown/whatsnewinmaven4.md: ########## @@ -0,0 +1,473 @@ +<!-- +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. +First, the POM holds all the information and configuration, which are only needed to build the artifact. +After the artifact is created, this build information is not relevant anymore. +Second, the POM also contains information, e.g. dependencies, which are needed by projects which want to use the +artifact. +These dependent projects 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. +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> + +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 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. + +## POM Changes + +### Build-POM and Consumer-POM + +Maven 3 uses Model version 4.0.0 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 therefore differentiates between a "Build-POM" and a "Consumer-POM". +As the names suggest, the "Build-POM" contains 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 to use an artifact as a dependency. +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 + +Maven 4 introduces a new POM 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. +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 as long as you don't want to make use of the new features. + +### Modules are now subprojects + +A Maven project is any Java project build with Maven. +The [directory][33] of a Maven project contains at least the source folder, the test source folder and the project's POM +file. +A Maven project may have other Maven projects within subdirectories. +Each project within a subdirectories is called "subproject". + +Example: A 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 as long as they are not linked as such in the POM file. +In the past this was done by listing each subproject in the `<modules>` section of the parent's POM. +The inconsistent wording led to the situation that many people calling subprojects "modules". +Projects which have at least one subproject are often called "multi-module project", while those which don't have any +are "single-module project". +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 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 | ✅ | ✅ | +| 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, 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, Review Comment: Created an issue to describe the terms in a separate PR. -- 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
