[
https://issues.apache.org/jira/browse/MNGSITE-550?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17908541#comment-17908541
]
ASF GitHub Bot commented on MNGSITE-550:
----------------------------------------
elharo commented on code in PR #598:
URL: https://github.com/apache/maven-site/pull/598#discussion_r1898740783
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# 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.
+
+> "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, and duplicate code
+which costs the developers who maintain Maven a lot of time.
+This means that the Maven codebase contains not only old Java code but also
old dependencies and poor API design of its
+own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped
into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only by the
build but also by consumers of the
+artifact.
+However, several 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.
+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" 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
+therefore related to the folder from where you start Maven.
Review Comment:
folder --> directory
related to or is?
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# 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.
+
+> "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, and duplicate code
+which costs the developers who maintain Maven a lot of time.
+This means that the Maven codebase contains not only old Java code but also
old dependencies and poor API design of its
+own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped
into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only by the
build but also by consumers of the
+artifact.
+However, several 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.
+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
Review Comment:
delete " or it may break your build (as shown in [MNG-8009][32])"
##########
content/markdown/whatsnewinmaven4.md:
##########
@@ -0,0 +1,466 @@
+# 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.
+
+> "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, and duplicate code
+which costs the developers who maintain Maven a lot of time.
+This means that the Maven codebase contains not only old Java code but also
old dependencies and poor API design of its
+own APIs, especially for Maven plugins.
+Therefore, Maven 4 will also be a maintenance release.
+
+This article presents and explains major changes brought by Maven 4, grouped
into several topics.
+
+## POM Changes
+
+### Build-POM and Consumer-POM
+
+As written in the introduction, Model version 4.0.0 is used not only by the
build but also by consumers of the
+artifact.
+However, several 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.
+While the new type is only available with Model Version 4.1.0, the final
outcome is a full Maven 3 compatible (model
Review Comment:
Try to be more precise. "final outcome" is unclear. Perhaps what's meant is
something like "The build pom is only available in Model version 4.1 and later
but the consumer pom is..."
> Information about "What's new in Maven 4?"
> ------------------------------------------
>
> Key: MNGSITE-550
> URL: https://issues.apache.org/jira/browse/MNGSITE-550
> Project: Maven Project Web Site
> Issue Type: Improvement
> Reporter: Matthias Bünger
> Priority: Major
>
> A comprehensive article/list of the important changes in Maven 4 is needed.
> ----
>
> Issue based on the slack message / thread, started by [~cstamas]
> {quote}
> More and more times we get questions like "and what is new in Maven4?". We
> have no document that distills the relevant changes. Could someone try to
> collect that in cwiki or somewhere?
> {quote}
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
