gnodet-bot commented on code in PR #13775: URL: https://github.com/apache/maven/pull/13775#discussion_r4436402866
########## src/site/markdown/aggregator-migration.md: ########## @@ -0,0 +1,213 @@ +<!-- +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. Review Comment: ⚠️ **Missing @Experimental notice:** `@After`, `@Resolution`, `@Execute`, and the Maven 4 `@Mojo` are all marked `@Experimental` in `maven-api-core` — they may change or be removed without notice. Add a warning here (or in a dedicated callout early in the document) so plugin authors know these APIs are not yet stable. ########## src/site/markdown/aggregator-migration.md: ########## @@ -0,0 +1,213 @@ +<!-- +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. + +## 1. Understand the existing behavior + +A legacy Mojo may declare itself as an aggregator: + +```java +@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. + +## 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 { + // ... +} +``` + Review Comment: 💡 **`@After` is `@Repeatable(Afters.class)`:** When a Mojo needs multiple ordering constraints (e.g. after both `compile` and `test-compile`), you can stack `@After` annotations. Consider adding a note or a brief example: ```java @After(phase = "compile") @After(phase = "test-compile") public class ReportMojo { // ... } ``` ########## src/site/markdown/aggregator-migration.md: ########## @@ -0,0 +1,213 @@ +<!-- +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. + +## 1. Understand the existing behavior + +A legacy Mojo may declare itself as an aggregator: + +```java +@Mojo(name = "report", aggregator = true) +public class ReportMojo { + // ... +} Review Comment: ⚠️ **Missing import and missing Maven 4 path:** Two issues here: 1. The legacy snippet has no `import` line — either add it for consistency with the Maven 4 example below (which includes imports), or add a comment that imports are omitted. 2. More importantly: Maven 4's `@Mojo` in `maven-api-core` also exposes an `aggregator()` field. For many plugins the simplest migration is simply switching to the Maven 4 `@Mojo` annotation with `aggregator = true` preserved. This direct path should be presented first before introducing `@After`. ########## src/site/site.xml: ########## @@ -39,6 +39,7 @@ under the License. <menu name="User Guide"> <item name="Configuring Maven" href="configuring.html"/> Review Comment: ⚠️ **Wrong section:** This guide targets *plugin developers*, not end users. Placing it in `<menu name="User Guide">` alongside "Configuring Maven" misclassifies the audience. It belongs in a plugin developer section (or wherever the plugin development guides live). ########## src/site/markdown/aggregator-migration.md: ########## @@ -0,0 +1,213 @@ +<!-- +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. + +## 1. Understand the existing behavior + +A legacy Mojo may declare itself as an aggregator: + +```java +@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. + +## 2. Express lifecycle ordering with `@After` + +The Maven API provides the `@After` annotation to express that a Mojo Review Comment: ⚠️ **What *does* provide 'once per reactor' semantics in Maven 4?** This paragraph correctly explains what `@After` does *not* do, but doesn't explain what a plugin author should use if they need the Mojo to run exactly once for the entire reactor. Please add a follow-up sentence or paragraph explaining the Maven 4 mechanism for reactor-wide single execution. -- 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]
