gnodet-bot commented on code in PR #13775: URL: https://github.com/apache/maven/pull/13775#discussion_r4458345183
########## src/site/markdown/aggregator-migration.md: ########## @@ -0,0 +1,867 @@ + +<!-- +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. +--> + +# Migrating Aggregator Mojos to Maven 4 Lifecycle Ordering + +This guide explains how Maven plugin authors can migrate from the legacy +`@Mojo(aggregator = true)` and `@Execute` APIs to Maven 4's explicit +lifecycle-ordering and dependency-resolution APIs. + +It covers: + +- The behavior of existing aggregator mojos with different Maven builders. +- The mapping from `aggregator = true` to `after:all` or `after:<phase>`. +- How to use `@Resolution` for dependency resolution. +- How to replace lifecycle forking with `@After`. +- How to access reactor projects through the `Session` API. +- Important behavioral differences between Maven builders. +- An incremental migration path for existing plugins. + +> **Important:** Existing plugins using `aggregator = true` do not necessarily +> need an immediate source migration. The concurrent-builder improvement +> proposed in [PR #13798](https://github.com/apache/maven/pull/13798) allows +> existing lifecycle-bound aggregator goals to receive the correct +> phase-specific ordering automatically when using a Maven version containing +> that change. The explicit lifecycle-ordering API remains the recommended +> approach for new plugins and for consistent behavior across builders. Review Comment: ⚠️ **@Experimental warning removed (regression from previous version):** The guide previously had: ``` > **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. ``` The rewrite replaced this with the PR #13798 callout and the @Experimental warning is now completely absent. Plugin authors adopting these APIs need this caveat — restore it (e.g. as a separate `> **Warning:**` block after the `> **Important:**` block). -- 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]
