gnodet opened a new issue, #13764: URL: https://github.com/apache/maven/issues/13764
## Summary Maven 4 provides a complete set of replacements for `aggregator=true` and `@Execute`, but there is no practical migration guide for plugin authors. PR #13330 adds an architecture specification, but a how-to guide with concrete code examples is needed to drive adoption. ## Problem Plugin authors who want to migrate from `aggregator=true`/`@Execute` to the new Maven 4 API have to piece together information from: - Annotation Javadoc (`@After`, `@Resolution`, `@Mojo`) - Integration test projects (`mng-8244-phase-all`, `mng-8653`) - Architecture spec in PR #13330 There is no single document that walks through the migration step by step with before/after code examples. ## Proposed Content A migration guide (e.g., `src/site/markdown/guides/plugin/aggregator-migration.md`) covering: ### 1. Mapping table | Old API | New API | Notes | |---|---|---| | `@Mojo(aggregator = true)` | Phase binding to `after:all` or `after:<phase>` | Controls when the mojo runs relative to child modules | | `@Mojo(aggregator = true)` resolution | `@Resolution(pathScope=..., requestType=...)` | Per-field dependency resolution injection | | `@Execute(phase = "...")` | `@After(phase = "...", type = ...)` | DAG ordering without lifecycle forking | | Reactor project list injection | `Session.getProjects()` API | Aggregator mojos received all projects automatically | | `<inherited>false</inherited>` | Implicit with `after:all` (runs on root only) | No longer needed | ### 2. Before/after code examples A complete example transforming a typical aggregator mojo (e.g., one that collects artifacts from all modules) from the old API to the new API. ### 3. Key behavioral differences - **Builder compatibility:** `before:`/`after:` phases work with **all** builders, not just the concurrent builder. (This is a common misconception — `MavenITmng8244PhaseAllTest` explicitly tests both legacy and concurrent builders.) - **Ordering guarantees:** With the concurrent builder, ordering is enforced by DAG edges instead of `aggregatorLock`. With legacy builders, `before:`/`after:` phases still work but ordering is sequential. - **No lifecycle forking:** `@After` specifies DAG ordering constraints without forking a parallel lifecycle. This eliminates the duplicate execution problem (MNG-7163 / #8291). - **Granular resolution:** `@Resolution` allows per-field control over dependency resolution scope and request type, replacing the all-or-nothing `AGGREGATOR` resolution scope. - **POM model version:** Phase bindings to `before:`/`after:` phases work with any POM model version (4.0.0 or 4.1.0). The `@After` and `@Resolution` annotations are part of the v4 API. ### 4. Incremental migration path Plugin authors don't need to migrate everything at once: 1. Start by rebinding from the declared phase to `after:<phase>` — this alone fixes the ordering problem 2. Replace `@Execute` with `@After` to eliminate lifecycle forking 3. Migrate dependency resolution to `@Resolution` for granular control 4. Replace reactor project injection with Session API ## Context - PR #13330 adds the architecture spec (`aggregator-goals.md`) — this guide would complement it - Integration test examples: `its/core/src/test/resources/mng-8244-phase-all/`, `its/core/src/test/resources/mng-8653-*/` - Related: #8718 (aggregator goals umbrella) _Claude Code on behalf of Guillaume Nodet_ -- 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]
