Skip to content

Add plugin author migration guide for aggregator=true to after:all #13764

Open

Description

@gnodet

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:

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 / [MNG-7163] Aggregating Mojo re-executes goals for child modules that are already executed #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

Claude Code on behalf of Guillaume Nodet

Activity

  1. codewithsinchana commented on Nov 1, 2026

    @codewithsinchana
    Contributor

    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!

  2. gnodet commented on Nov 3, 2026

    @gnodet
    ContributorAuthor

    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) to after: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 to after:all:

    • It works without any plugin change — existing aggregator=true plugins get correct ordering in -b concurrent builds automatically
    • It suppresses inherited copies when an ancestor in the active reactor already provides the execution (no need for <inherited>false</inherited>)
    • But it only applies to the concurrent builder — singlethreaded and -T N are unchanged

    What this means for the guide

    The mapping table row @Mojo(aggregator=true) → after:all is 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:

    • With -b concurrent, aggregator=true plugins work correctly without migration
    • On singlethreaded/-T N, the lifecycle-bound aggregator-runs-per-module problem (MNG-6336) remains open regardless of Fix concurrent builder ordering for lifecycle-bound aggregators #13798
    • after:all + @Resolution remains the recommended API for new plugins: it's explicit, composable, and works correctly across all builders without special-casing in the planner

    Should we still deprecate aggregator=true?

    Yes, but the rationale shifts. The argument is no longer "it's broken, migrate" — it becomes:

    1. Semantic ambiguity: the flag conflates ordering, resolution scope, and inheritance suppression in one boolean
    2. Maintenance burden: correct ordering requires special-casing in the build planner; after:all is just a phase binding
    3. Singlethreaded/-T N gap: MNG-6336 (lifecycle-bound aggregators run per-module) remains open and won't be fixed on the legacy builders
    4. The @Execute replacement path (@After) is independent and still fully motivated

    The 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 @After annotations 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 generates plugin.xml including <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 @After support; the built-in processor already handles it.

    Suggested update to the guide scope

    Add a "builder compatibility matrix" section:

    Problem Singlethreaded -T N -b concurrent
    Aggregator runs only at root ✅ ✅ ✅
    Aggregator runs after children finish phase ✅ (sequential) ✅ (aggregatorLock) ✅ after #13798
    Lifecycle-bound aggregator runs per-module ⚠️ MNG-6336 ⚠️ MNG-6336 ✅ fixed

    And step 0 in the incremental migration path: "Your existing plugin already behaves correctly in -b concurrent builds after Maven 4.x.y (MNG-XXXX). Migration to after:all is recommended for new plugins and for full correctness across all builders."

  3. added a commit that references this issue on Nov 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions