gnodet-bot commented on code in PR #13775: URL: https://github.com/apache/maven/pull/13775#discussion_r4442962055
########## src/site/markdown/aggregator-migration.md: ########## @@ -0,0 +1,305 @@ +<!-- +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 + + https://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. +--> + +# Migrating Aggregator Mojos to Lifecycle Ordering + +This guide helps Maven plugin authors evaluate whether a Mojo using +`aggregator = true` or lifecycle forking should migrate to lifecycle +ordering with `@After` and phases such as `after:all`. + +**Important:** `aggregator = true`, lifecycle forking, and lifecycle ordering +serve different purposes. They are not interchangeable. Choose the migration +based on the behavior the plugin requires. + +> **Warning:** The Maven 4 APIs discussed in this guide, including +> `@Mojo`, `@After`, `@Resolution`, and `@Execute`, are marked +> `@Experimental`. Their contracts may change or the APIs may be +> removed without notice. Plugin authors should take this into +> account before adopting them in production plugins. + +## 1. Understand the existing behavior + +A legacy Mojo may declare itself as an aggregator: + +```java +import org.apache.maven.plugins.annotations.Mojo; + +@Mojo(name = "report", aggregator = true) +public class ReportMojo { + // ... +} +``` + +Aggregator status affects how a goal operates in a multi-project build. +It does not, by itself, express a precise ordering dependency on another +lifecycle phase. + +Some legacy Mojos also use `@Execute` to request execution of another +goal or lifecycle phase. This introduces lifecycle-forking behavior that +must be considered separately when migrating. + +Before changing an annotation, identify whether the Mojo needs to: + +- Run once for a multi-project build rather than once per project. +- Run after a particular lifecycle phase has completed. +- Access information or dependencies from other projects. +- Fork another lifecycle or goal before executing its own work. + +These requirements are distinct and may require different solutions. + +### Direct migration to the Maven 4 `@Mojo` annotation + +Maven 4 provides its own `@Mojo` annotation in +`org.apache.maven.api.plugin.annotations`. It retains the +`aggregator` attribute. + +If a plugin needs to preserve its existing aggregator behavior while +adopting the Maven 4 annotation, it can retain `aggregator = true`: + +```java +import org.apache.maven.api.plugin.annotations.Mojo; + +@Mojo(name = "report", aggregator = true) +public class ReportMojo { + // ... +} +``` + +This is the direct annotation migration path. The Maven 4 `aggregator` +attribute identifies a Mojo that uses the Maven project and its +subprojects. + +However, retaining `aggregator = true` does not express a specific +lifecycle-ordering relationship. If the plugin requires execution +after a particular phase or after the entire reactor, consider the +lifecycle-ordering mechanisms described below. + +## 2. Express lifecycle ordering with `@After` + +The Maven API provides the `@After` annotation to express that a Mojo +must run after a specified lifecycle phase. + +For example: + +```java +import org.apache.maven.api.plugin.annotations.After; +import org.apache.maven.api.plugin.annotations.Mojo; + +@Mojo(name = "report") +@After(phase = "resources") +public class ReportMojo { + // ... +} +``` + +This declares an ordering constraint relative to the `resources` phase. +It does not, on its own, make the Mojo an aggregator or guarantee that it +runs only once for the entire reactor. + +The `@After` annotation is repeatable. A Mojo can declare multiple +ordering constraints when it must run after more than one phase: + +```java +@After(phase = "compile") +@After(phase = "test-compile") +public class ReportMojo { + // ... +} Review Comment: 💡 **Nit (re-raise):** This repeatable `@After` snippet still omits `@Mojo(name = "report")`. Every surrounding example — including the one immediately above — includes it. Omitting it here implies the annotation is optional when stacking `@After`, which is misleading. ```suggestion @Mojo(name = "report") @After(phase = "compile") @After(phase = "test-compile") public class ReportMojo { // ... } ``` -- 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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
