docs: document seeding the Maven cache for plugin dependencies

[brunoborges]

Description:

With cache: maven, the action stores whatever a run downloads into ~/.m2 and does not re-save on a cache hit. Because Maven resolves plugin dependencies lazily (only for the goals that actually execute), a cache first created by a "thin" goal such as mvn compile never captures plugins bound to later phases. For example maven-shade-plugin and its dependencies (plexus-archiver, commons-compress, aircompressor, xz) are missing, so every later test/verify/package job re-downloads them on each run. The same effect hits parallel matrix jobs that each run a partial goal and race to save an incomplete cache (issue #705). This behavior was reproduced and confirmed on the current main.

This is a documentation-only change. It explains the behavior and shows how to seed a complete cache; it does not change the action's caching code.

• README.md: a short note under "Caching maven dependencies" that states the problem in a couple of lines and links to the advanced guide.
• docs/advanced-usage.md: a new "Ensuring the Maven cache is complete (plugin dependencies)" section with the root-cause explanation, a comparison of seed commands (dependency:resolve alone is insufficient; dependency:resolve-plugins / dependency:go-offline cover plugin deps), a single-job example, and a separate-seed-job (matrix) example that addresses the parallel multi-job race in Add extra cache key for multiple jobs on the same pom, but a different part #705, plus caveats.

The recommended seed is mvn -B dependency:go-offline dependency:resolve-plugins, verified to produce a superset that lets a subsequent build download nothing.

The section is honest about limits: the seed only helps on the run that creates the cache (an already-incomplete cache must be invalidated once), static resolution is not exhaustive (profile/module/execution-time gaps), and multi-module builds should seed at the reactor root. A closing note flags that cache: gradle has the same limitation and points Gradle users to gradle/actions/setup-gradle for complete dependency caching.

Related issue:
Fixes: #990
Addresses: #705

Check list:

• Ran npm run check locally (format, lint, build, test) and all checks pass. (N/A: docs-only; npm run check targets .ts/.yml, not Markdown.)
• Mark if documentation changes are required.
• Mark if tests were added or updated to cover the changes. (N/A: documentation-only change.)

[Copilot]

Pull request overview

Documentation update explaining a common limitation of cache: maven in actions/setup-java: Maven plugin dependencies are resolved lazily, so an initial cache created by a “thin” goal may not include plugin deps, causing repeated downloads on subsequent CI runs.

Changes:

• Added a brief note in the README under “Caching maven dependencies” pointing to an advanced guide section.
• Added a new advanced-usage section describing why plugin deps can be missing and how to seed a more complete Maven cache (with examples and caveats).

Show a summary per file

File	Description
README.md	Adds a short note linking to the advanced guidance about seeding Maven plugin dependencies into the cache.
docs/advanced-usage.md	Adds a new section detailing the root cause and recommended seeding commands/workflow patterns to produce a more complete Maven cache.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 2/2 changed files
• Comments generated: 1
• Review effort level: Low