Add Vision document for Java Modules in Maven 4 by ascheman · Pull Request #1 · support-and-care/maven-modular-sources-docs

ascheman · 2026-01-19T21:01:37Z

Summary

Add comprehensive Vision document explaining Java Modules support in Maven 4
Introduce three-phase lifecycle model (compile, test, runtime) clarifying Maven vs JVM responsibilities
Document the shift from 1:1 Maven-module-to-JAR to many:1 modular sources pattern

Key Content

The Vision document covers:

How Java Modules work - JPMS fundamentals (requires, exports, encapsulation)
Lifecycle Phases and Module Enforcement - When Maven orchestrates vs when JVM takes over
How Maven worked with Modules in the past - Maven 3's 1:1 mapping limitations
How Maven 4 envisions Modules - Module Source Hierarchy pattern
Implications - Forward references to planned documentation topics

Context

Part of the documentation effort described in Discussion #155.

Test plan

Review document structure and flow
Verify technical accuracy of lifecycle phase descriptions
Check cross-references work correctly

🤖 Generated with Claude Code

Describes the shift from Maven modules to Java Modules as primary compilation units, including: - How Java Modules work - How Maven 3 handled modules - Maven 4's Module Source Hierarchy approach - Implications for dependency resolution and testing 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> Ref: support-and-care/maven-support-and-care#158

* Add "Lifecycle Phases and Module Enforcement" section with three-phase model (compile, test, runtime) * Add responsibility boundary table showing Maven vs JVM control * Add CAUTION about special cases (Exec Plugin, integration tests) * Refactor "Why This Distinction Matters" to be conceptual * Refactor "Implications" as documentation index with TBD items * Convert lead paragraph to TL;DR sidebar * Expand JPMS acronym with aliases 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> Ref: support-and-care/maven-support-and-care#158

github-actions · 2026-01-19T21:02:09Z

🚀 Deployed on https://pr-1--maven-modular-sources-docs.netlify.app

Copilot

Pull request overview

This PR adds a comprehensive Vision document that articulates Maven 4's approach to Java Modules support, introducing the Module Source Hierarchy pattern that shifts from Maven 3's 1:1 Maven-module-to-JAR mapping to a many:1 modular sources pattern.

Changes:

Introduces comprehensive Vision document explaining Java Modules (JPMS) fundamentals and Maven 4's approach
Establishes three-phase lifecycle model (compile, test, runtime) clarifying Maven vs JVM responsibilities
Updates index.adoc to link to the new Vision document

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
docs/vision.adoc	New comprehensive Vision document covering Java Modules fundamentals, Maven's lifecycle phases, historical context, and the new Module Source Hierarchy pattern
docs/index.adoc	Updated Topics table to link to the new Vision document

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

* Fix double spaces in TL;DR sidebar * Clarify JAR output phrasing per Copilot review * Fix missing space in dependency resolution section 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> Ref: support-and-care/maven-support-and-care#158

desruisseaux · 2026-02-05T11:55:24Z

+.TL;DR
+****
+Java Modules enable strong encapsulation and explicit dependencies at the language level.
+It is possible to define them in a single source tree separated by module names.


This sentence gives the impression that "them" is referring to source code, as "it is possible to define Java source files in a single source tree separated by module names" would be correct. But the sentence just before talk about dependencies…

Rephrased to "Their source code can be organized in a single source tree, separated by module names." and added a sentence about Maven assembling the module-path for dependency resolution. Fixed in commit 569e61f.

desruisseaux · 2026-02-05T11:59:04Z

+=== Three Distinct Phases
+
+Compile time::
+Maven orchestrates the build environment by resolving dependencies and constructing the module path.


Shouldn't "module path" be "paths to module source files"?

I was mostly thinking of the module-path, with modular dependencies as JARs, directories of such JARs or perhaps other (unpacked modular class file diretories). I'll think about a reformulation.

Clarified the text to distinguish between module source path and module path. Maven now "sets up the module source path and module path for the compiler" and "translates its dependency model into the module path of dependency JARs." Fixed in commit 569e61f.

desruisseaux · 2026-02-05T12:05:24Z

+The critical insight: *Maven's responsibility ends at packaging.*
+Once Maven has produced and deployed JARs, they must be self-sufficient.
+The `module-info.class` in each JAR must accurately declare what the JVM will need to run the application.
+


But we still need to specify a module-path. However, the module-path could point to a single directory containing all JAR files, and the JVM will pickup only what it needs according module-info.

Qualified "Classpath-based" to "Classpath-based by design" and added: "With Java Modules, the JVM requires a module-path to resolve modules at runtime, but Maven 3's architecture remained classpath-centric." Fixed in commit 569e61f.

desruisseaux · 2026-02-05T12:14:23Z

+* The compiler plugin (and others) gained module support
+* Each Java Module still requires its own Maven module
+* No native support for multi-module compilation
+


Other limitations were:

Automatic detection of whether to place a dependency on class-path or module-path, with no control in case of wrong detection.

No easy way to setup options such as --patch-module for whitebox testing. Instead, a common practice was to overwrite the full module-info.java file in the test, which has drawbacks.

Incorporated both points into the Maven 3 adaptation list: classpath/module-path auto-detection with limited control, and the module-info.java overwrite workaround for whitebox testing. Fixed in commit 569e61f.

desruisseaux · 2026-02-05T12:16:52Z

+
+Flexible artifact mapping::
+One Maven project can produce multiple module JARs (in the future).
+


Pull request is almost ready, waiting only for 4.0.0-rc-6 release: apache/maven-jar-plugin#508

I didn't want to explicitly refer to PR #508 but intentionally avoided referencing ongoing work in the vision document. I plan to cover artifact naming details in a separate document.

desruisseaux · 2026-02-05T12:19:25Z

+How whitebox testing works with `--patch-module` and how Maven 4's compiler plugin handles test sources automatically.
+
+Artifact Naming (TBD)::
+How Java module names map to Maven artifact coordinates when one project produces multiple JARs.


In above-cited pull request for Maven JAR plugin, the Java module name maps directly to the artifact name.

Agreed. I am preparing additional documents (including artifact naming analysis) but wanted the vision document to pass review first before expanding the scope.

* Clarify TL;DR: fix ambiguous "them", add dependency resolution * Distinguish module source path from module path at compile time * Qualify "Classpath-based" as "by design", add runtime module-path note * Add Maven 3 limitations: classpath/module-path detection, patch-module 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> Ref: support-and-care/maven-support-and-care#158

* Use "Apache Maven" for first occurrence in each document * Add trademark footer to all AsciiDoc files 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> Ref: support-and-care/maven-support-and-care#158

ascheman added 2 commits January 19, 2026 21:53

ascheman self-assigned this Jan 19, 2026

ascheman requested a review from Copilot January 19, 2026 21:20

Copilot started reviewing on behalf of ascheman January 19, 2026 21:20 View session

Copilot AI reviewed Jan 19, 2026

View reviewed changes

Comment thread docs/vision.adoc Outdated

Comment thread docs/vision.adoc Outdated

Comment thread docs/vision.adoc Outdated

Comment thread docs/vision.adoc Outdated

desruisseaux reviewed Feb 5, 2026

View reviewed changes

ascheman added 2 commits February 6, 2026 17:58

desruisseaux approved these changes Feb 7, 2026

View reviewed changes

ascheman merged commit f6c1588 into main Feb 7, 2026
2 checks passed

ascheman deleted the feature/vision branch February 7, 2026 12:09


		Flexible artifact mapping::
		One Maven project can produce multiple module JARs (in the future).

Uh oh!

Conversation

ascheman commented Jan 19, 2026

Summary

Key Content

Context

Test plan

Uh oh!

github-actions Bot commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ascheman Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions Bot commented Jan 19, 2026 •

edited

Loading

ascheman Feb 5, 2026 •

edited

Loading