Improving Documentation for Java Modules in Maven 4

[ascheman]

TL;DR

We lack centralized documentation about Java Modules support in Maven, particularly for Maven 4's new API architecture. This discussion aims to coordinate a documentation effort to address this gap. See Personal Proposal by Gerd Aschemann at the end for a concrete starting point.

Note: Java Modules refers to the module system introduced in Java 9, also known as JPMS (Java Platform Module System) or by its development code name "Jigsaw".

Problem Statement

Currently, there is insufficient centralized documentation covering:

1. Java Modules fundamentals - The Java Module system itself needs to be introduced, at least the aspects relevant to Maven (e.g., module descriptors, module path vs. classpath, encapsulation, services)
2. State of the art - The current state of Java Modules support in Maven needs to be described. Some Confluence and GeoMatys Wiki pages exist and provide a good starting point, but they are scattered and incomplete (see Existing Resources below)
3. Maven 4 API and Java Modules - There is little internal documentation about the new Maven 4 API layer (maven-api-*) and how it relates to Java Modules
4. Design rationale - Why certain architectural decisions were made and what trade-offs were considered

This makes it difficult for Maven team members to:

• Understand how Maven (currently) does and (in the future) should support building and using Java Modules
• Reason about the implications of Java Modules for Maven's architecture
• Make informed decisions when improving Java Modules support in Maven

Proposed Documentation Scope

The documentation effort could cover:

• Maven's current Java Modules support and limitations
• How the Maven 4 API enables Java Modules support
• How Maven handles module path, classpath, and mixed scenarios
• Rationale behind design decisions for Java Modules support
• Known issues and gaps in Java Modules support

Out of Scope

This initial documentation effort focuses on internal knowledge for the Maven team. The following topics are explicitly out of scope for now but may be addressed in follow-up efforts:

• End-user guides for building modular projects with Maven
• Plugin developer documentation for module-aware plugins
• Migration guides for users upgrading to Maven 4
• Tutorials and how-to articles for general audiences

These topics are important but require the foundational internal documentation to be in place first.

Questions for Discussion

Where should this documentation live and how should it be published?

A docs-as-code approach enables developer workflows like versioning, pull requests, and review processes. Each option has different trade-offs for writing and publishing:

1. Maven website (maven.apache.org)

   • Good for final, polished results (parts should eventually go there)
   • Hard for day-to-day work due to publication workflow and release cycles

2. Confluence

   • Easy to use and publish
   • No version control
   • Option: Automatically push docs-as-code generated pages to Confluence

3. In-repository documentation (e.g., in maven-core)

   • Good location, close to the code
   • Similar publication challenges as Maven website
   • Currently lacks process and tooling for very frequent updates

4. Dedicated documentation repository

   • Allows frequent updates and streamlined publication
   • Can publish to GitHub Pages with PR previews (e.g., via Netlify)
   • Enables contribution workflow independent of Maven release cycles

5. Combination - TBD

Note: The documentation should eventually be under ASF governance, but initially we should enable easy contribution, including from non-committers.

What format/structure works best?

The documentation could evolve through different forms:

• Single-topic articles - Individual pieces covering specific aspects (similar to blog posts or discussion summaries), easy to contribute incrementally
• Conceptual documentation - Comprehensive and concise explanations of core concepts, consolidating insights from single-topic articles
• Reference documentation - Structured technical reference for long-term use

These are not mutually exclusive—single-topic articles can feed into conceptual docs, which in turn inform the reference documentation.

What knowledge should be captured first?

• Historical decisions and their rationale?
• Current state of Java Modules support?
• Future direction and open questions?

What document format should we use?

• Markdown - Widely supported, simple syntax, good GitHub rendering, limited features
• AsciiDoc - Richer feature set (callouts, admonitions, includes, cross-references), better for technical documentation, requires tooling for rendering

AsciiDoc offers more capabilities for structured technical documentation but has a steeper learning curve. Markdown is more accessible but may limit advanced formatting options.

Existing Resources

Confluence (ASF)

• Full Java Modules Support - Current State - Overview of Java Modules support status in Maven
• Default directory for modular projects - Discussion on directory layout for modular projects
• Build Sources Validation - Discussion Notes - Notes on modular source validation

GeoMatys Wiki

• Geomatys Maven Compiler Plugin Wiki - User Guide - Modular project configuration
• Geomatys Maven Compiler Plugin Wiki - Migration - Migration guide for modular projects
• Geomatys Maven Wiki - General Maven documentation

Java Modules Examples

• Java 9 Jigsaw Examples - Comprehensive examples demonstrating Java Modules features
• Java 9 Jigsaw Examples - GitHub Pages - Rendered documentation

Related Pull Requests (recent)

Maven Core:

• #11505 - Add module-aware resource handling for modular sources
• #11549 - Accept Java module names as attached artifactId

Maven Compiler Plugin:

• #959 - Build projects that are both multi-module and multi-release (merged)

Maven JAR Plugin:

• #508 - Migrate from Maven Archiver to standard jar tool (draft, multi-module support)

To Be Investigated

• Maven Site
• Mailing list discussions (dev@maven.apache.org)
• Related GH or even JIRA issues
• External blog posts and tutorials
• Oracle/OpenJDK documentation on Java Modules

Next Steps

1. Propose documentation structure and location - Make a concrete proposal for where and how to organize the documentation
2. Describe a vision - How Java Modules could/should work in the Maven ecosystem
3. Start writing foundational sections - Begin with topics where understanding already exists (Java Modules fundamentals, state of the art)
4. Document internal architecture - How Maven currently handles Java Modules internally
5. Capture known challenges - Document open issues and design challenges to encourage further discussion

---

Personal Proposal by Gerd Aschemann

I propose to use the existing Java 9 Jigsaw Examples repository as the foundation for this documentation effort:

Reasons:

• Already has a working build and publication process (GitHub Pages + Netlify for previews)
• Well-structured examples covering many Java Modules features and their interaction with Maven
• Contains working code examples that can be referenced directly
• Allows documentation to evolve alongside executable examples (code)
• Using AsciiDoc enables including code snippets from actual source files, ensuring documentation stays in sync with working code

Current drawback:

• The published GitHub Pages currently lack navigation structure (but this can be easily addressed)

I could even propose a small example how the documentation could look like using AsciiDoc with included code snippets from the examples in this repository.

Whatever approach is chosen, we can migrate the documentation later to other platforms (Maven website, Confluence, ...) as needed.

---

This discussion was initiated to coordinate community input before starting the documentation work.