Repository navigation
Description
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 [MNG-7991] Document aggregator goal lifecycle behavior and design spe… #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 —MavenITmng8244PhaseAllTestexplicitly 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:
@Afterspecifies DAG ordering constraints without forking a parallel lifecycle. This eliminates the duplicate execution problem (MNG-7163 / [MNG-7163] Aggregating Mojo re-executes goals for child modules that are already executed #8291). - Granular resolution:
@Resolutionallows per-field control over dependency resolution scope and request type, replacing the all-or-nothingAGGREGATORresolution scope. - POM model version: Phase bindings to
before:/after:phases work with any POM model version (4.0.0 or 4.1.0). The@Afterand@Resolutionannotations are part of the v4 API.
4. Incremental migration path
Plugin authors don't need to migrate everything at once:
- Start by rebinding from the declared phase to
after:<phase>— this alone fixes the ordering problem - Replace
@Executewith@Afterto eliminate lifecycle forking - Migrate dependency resolution to
@Resolutionfor granular control - Replace reactor project injection with Session API
Context
- PR [MNG-7991] Document aggregator goal lifecycle behavior and design spe… #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: [MNG-7991] refactor "aggregator" goal feature #8718 (aggregator goals umbrella)
Claude Code on behalf of Guillaume Nodet
Activity
Fix aggregator-goals.md: before:/after: phases work with all builders
codewithsinchana commentedon Nov 1, 2026
Hi @gnodet, I'd like to contribute to this issue by preparing the plugin author migration guide with practical before-and-after examples, API mappings, behavioral differences, and an incremental migration path.
I'll first review the existing Maven 4 annotations, architecture specification, and integration tests to ensure the documentation accurately reflects the current implementation. Please let me know if anyone is already working on this issue. Thank you!
gnodet commentedon Nov 3, 2026
PR #13798 changes the picture enough that this issue's framing needs an update before anyone writes the guide.
What #13798 does
Instead of mapping
@Mojo(aggregator=true)toafter:all, it makes the concurrent builder auto-schedule aggregator goals as DAG steps after the children have completed the declared phase. This is not the same as binding toafter:all:aggregator=trueplugins get correct ordering in-b concurrentbuilds automatically<inherited>false</inherited>)-T Nare unchangedWhat this means for the guide
The mapping table row
@Mojo(aggregator=true)→after:allis still the right long-term target, but the guide should not frame it as "migrate or your plugin is broken". The correct framing after #13798:-b concurrent,aggregator=trueplugins work correctly without migration-T N, the lifecycle-bound aggregator-runs-per-module problem (MNG-6336) remains open regardless of Fix concurrent builder ordering for lifecycle-bound aggregators #13798after:all+@Resolutionremains the recommended API for new plugins: it's explicit, composable, and works correctly across all builders without special-casing in the plannerShould we still deprecate
aggregator=true?Yes, but the rationale shifts. The argument is no longer "it's broken, migrate" — it becomes:
after:allis just a phase binding-T Ngap: MNG-6336 (lifecycle-bound aggregators run per-module) remains open and won't be fixed on the legacy builders@Executereplacement path (@After) is independent and still fully motivatedThe deprecation should land once: (a) #13798 is merged, (b) at least one major plugin (javadoc, site) has migrated to demonstrate the new API is practical, and (c) plugin descriptor generation from
@Afterannotations is available without external tooling.On that last point: #13658 (
maven-api-plugin-processor) adds a JSR 269 annotation processor directly into apache/maven that generatesplugin.xmlincluding<afterLinks>at compile time with zero external dependencies. Once that lands, maven-plugin-tools is no longer needed for Maven 4 plugins — its deprecation for Maven 4 follows naturally. Plugin authors won't need to wait for maven-plugin-tools to grow@Aftersupport; the built-in processor already handles it.Suggested update to the guide scope
Add a "builder compatibility matrix" section:
-T N-b concurrentaggregatorLock)And step 0 in the incremental migration path: "Your existing plugin already behaves correctly in
-b concurrentbuilds after Maven 4.x.y (MNG-XXXX). Migration toafter:allis recommended for new plugins and for full correctness across all builders."[MNG-7991] Document aggregator goal lifecycle behavior and design spe… (