Bukama commented on code in PR #759: URL: https://github.com/apache/maven-site/pull/759#discussion_r2051552999
########## content/markdown/guides/mini/guide-migration-to-mvn4.md: ########## @@ -0,0 +1,339 @@ +# Migrate to Maven 4 + +<!-- +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. +--> + +Maven 4 introduces several upgrades and improvements (see ["What's new in Maven 4?"](/whatsnewinmaven4.html)). +Some of them are backwards compatible or optional, but some require changes of your build environment or Maven project. +This page offers help for users who want to build their projects with Maven 4. + +In short, the general suggestion for the migration is to do it in three steps: + +1. Meet the prerequisites +2. Use Maven 4 for your build and fix build errors +3. Introduces optional Maven 4 features + +If you run into any issues, please don't hesitate to contact the [users mailing list](/mailing-lists.html). +The Maven team is interested in all your migration experiences - either good or bad! + +**Notes**: + +* This page will constantly be updated to contain changes, but also to integrate feedback of the community and their experience when upgrading to Maven 4. + This means it will still receive updates after Maven 4 was already released. +* It is planed to provide a migration tool (see [MNG-8649](https://issues.apache.org/jira/projects/MNG/issues/MNG-8649)), doing most of the steps needed to migrate a project. +* This guide does not contain information about how to update plugins to use the new Maven 4 plugin API. + It is planed to create a separate guide for this. + +## Table of content + +<!--MACRO{toc|fromDepth=2|toDepth=4}--> + +## Prerequisites + +This guide assumes that your environment and project meets the following prerequisites. +If they don't fulfill them already, please put effort into meeting them, before continuing with this guide. + +### Use latest version of Maven 3.9 + +This guide assumes that the project to be migrated was successfully built using the [latest version of Maven 3](/docs/history.html). + +### Upgrade plugins to their latest Maven 3 version + +Similar to the previous prerequisite, the guides assumes that you are using the latest Maven 3 plugin version of all your plugins. + +Do not upgrade to a plugin version, which requires Maven 4! +Be aware of this, if you use tools that can automate updates. + +You can use the [versions-maven-plugin's `display-plugin-updates` goal][versionpluginupdate], to see which are the latest available versions of the plugins you use. + +The following example shows the output of the Versions Maven Plugin in a project using the outdated version 3.12.0 of the maven-compiler-plugin. +As you can see, it shows that with version 3.14.0 there is a Maven 3 compatible update, while the versions 4.0.0-beta-1 and 4.0.0-beta-2 require Maven 4 versions. + +``` +[INFO] The following plugin updates are available: +[INFO] maven-compiler-plugin ............................ 3.12.0 -> 3.14.0 +[INFO] +[INFO] All plugins have a version specified. +[INFO] +[INFO] Project requires minimum Maven version for build of: 3.9 +[INFO] Plugins require minimum Maven version of: 3.6.3 +[INFO] +[INFO] No plugins require a newer version of Maven than specified by the pom. +[INFO] +[INFO] Require Maven 4.0.0-beta-3 to use the following plugin updates: +[INFO] maven-compiler-plugin ...................... 3.12.0 -> 4.0.0-beta-1 +[INFO] +[INFO] Require Maven 4.0.0-rc-2 to use the following plugin updates: +[INFO] maven-compiler-plugin ...................... 3.12.0 -> 4.0.0-beta-2 +``` + +## Required changes + +You need to do the following steps to be able to use Maven 4. + +### Upgrade build environment to support Java 17 + +Maven 4 requires Java 17 to be run. +This means the build environment (locally but also your CI environment) needs to provide a JDK that supports Java 17. +Either install one to your machine or use a container providing one. + +**Note**: Maven 3 can also use executed with Java 17. +So you should prepare your build environment as soon as possible to have a solid, project independent base for further migration. + +### Install and use Maven 4 + +After you have upgraded your build environment to support Java 17, you also need to provide Maven 4. +See the information [where to download](/download.cgi) and [how to install](/install.html) Maven 4 for further information. + +Places where you might have to configure Maven 4 usage aside installation: +* [Maven Wrapper](/wrapper/index.html)'s `maven-wrapper.properties` file. +* [Required Maven version](/enforcer/enforcer-rules/requireMavenVersion.html) rule of the Maven enforcer plugin. +* Your own CI/CD configuration scripts or pipelines. + +### Update plugins to Maven 4 version + +If there is a dedicated Maven 4 version for used plugins, you should update to such a version. +You can use the [Versions Maven Plugin's `display-plugin-updates` goal][versionpluginupdate] to check for updates. + +**Note**: While Maven 4.0.0 aims to support all Maven 3.9 compatible plugins, this can not be guaranteed for custom plugins which use outdated plugin API methods. + +## Troubleshooting and required changes if situation applies + +The following changes are in general not required by all projects, but might apply to yours. + +### Fix plugin misconfigurations + +There are several misconfigurations in the project's POM declaration that result in warnings when using Maven 3.9. +While your build should not throw any warnings at all, the following ones needs to be fixed as they will fail the build in Maven 4. + +**Notes**: +* The [plugin configuration guide](/guides/mini/guide-configuring-plugins.html) contains general information, how plugins are correctly declared and configured. +* For analysing wrong build behavior, it might help to use the new `--fail-on-severity` parameter, paired with `WARN` as an argument, to fail your build when a warning occur. + +#### Duplicate plugin declaration + +A plugin must only be declared once. +Defining it multiple times, results the following log message. + +> 'build.plugins.plugin.(groupId:artifactId)' must be unique but found duplicate declaration of plugin [plugin-name] ... + +To fix this, remove the duplicated configuration. Review Comment: > Wouldn't it make more sense to write something like "merge the plugin declarations"? I was thinking about that, but I thought it might cause confusion, because plugin configuration (and execution) of the same plugin can be merged (parts that are declared in parent and those that are added / overwritten in child). -- 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
