Fail on legacy config in modular projects by ascheman · Pull Request #11702 · apache/maven

ascheman · 2026-02-06T09:45:38Z

NOTE: This summary is somewhat outdated, check for an update comment below, for clarification what this PR finally does.

Summary

Legacy directories and resources that conflict with modular sources now trigger an ERROR instead of WARNING
Prevents silent loss of user-configured sources/resources
AC8 supersedes AC7 which originally used WARNING

Affected configurations in modular projects:

Explicit <sourceDirectory>/<testSourceDirectory> differing from defaults
Default src/main/java or src/test/java existing on filesystem
Explicit <resources>/<testResources> differing from Super POM defaults

Test plan

ProjectBuilderTest#testModularSourcesWithExplicitResourcesIssuesError passes
ProjectBuilderTest#testMixedSourcesModularMainClassicTest passes

Fixes #11701
See #11701 (comment)

🤖 Generated with Claude Code

ascheman · 2026-02-06T13:27:44Z

Reviews are welcome, in particular from @elharo and @desruisseaux - thanks!

elharo

not obvious to me how claude code is being used here. Generally I would not expect simply pointing it at this issue without human editing to produce correct results.

elharo · 2026-02-06T18:27:37Z

impl/maven-core/src/main/java/org/apache/maven/project/DefaultProjectBuilder.java

                 *
                 * Additionally, for modular projects, legacy directories are unconditionally
-                 * ignored because it is not clear how to dispatch their content between
+                 * rejected because it is not clear how to dispatch their content between


I don't think this is what we were looking for. The build fails completely, not simply a warning

Proposal: replace "A warning is emitted if …" by "The build fails if …".

elharo · 2026-02-06T18:29:25Z

impl/maven-core/src/main/java/org/apache/maven/project/DefaultProjectBuilder.java

         * </ul>
-         * Legacy directories are unconditionally ignored in modular projects because it is not clear
-         * how to dispatch their content between different modules.
+         * In both cases, the legacy directory conflicts with modular sources and must not be used.


not "and must not be used" but rather the complete build fails.

not "and must not be used" but rather the complete build fails.

Isn't what the next line below is saying?

elharo · 2026-02-06T18:30:36Z

impl/maven-core/src/main/java/org/apache/maven/project/SourceHandlingContext.java

-                            scopeId,
-                            sourcesConfig);
+                    String message = String.format(
+                            "Legacy %s element must not be used because %s resources are configured via %s in <sources>.",


must not be used --> cannot be used in modular projects

elharo · 2026-02-06T18:30:47Z

impl/maven-core/src/main/java/org/apache/maven/project/SourceHandlingContext.java

                if (hasExplicitLegacyResources(resources, scopeId)) {
                    String message = "Legacy " + legacyElement
-                            + " element is ignored because modular sources are configured. "
+                            + " element must not be used because modular sources are configured. "


must not --> cannot

elharo · 2026-02-06T18:31:10Z

impl/maven-core/src/main/java/org/apache/maven/project/SourceHandlingContext.java

-                            scopeId,
-                            sourcesConfig);
+                    String message = String.format(
+                            "Legacy %s element must not be used because %s resources are configured via %s in <sources>.",


elharo · 2026-02-06T18:31:59Z

impl/maven-core/src/test/java/org/apache/maven/project/ProjectBuilderTest.java

-     * Acceptance Criterion: AC2 (unified source tracking for all lang/scope combinations)
+     * Acceptance Criteria:
+     * - AC2 (unified source tracking for all lang/scope combinations)
+     * - AC8 (legacy directories error - supersedes AC7 which originally used WARNING)


not sure how the AC are being used, but shouldn't AC7 be changed rather than superseded?

As AC7 has already become part of the master branch implementation, I do not want to override it now. I consider it better to invalidate it and write a new one. As they all belong to proper legacy source/resource handling wrt to the new <sources> configuration element, I proceed with the numbering. I am also preparing some overall documentation, covering all aspects (an update/replacement for the Confluence page where it all began.

elharo · 2026-02-06T18:32:48Z

impl/maven-core/src/test/java/org/apache/maven/project/ProjectBuilderTest.java

-     * In modular projects, legacy directories are unconditionally ignored because it is not clear
-     * how to dispatch their content between different modules. A warning is emitted if these
-     * properties are explicitly set (differ from Super POM defaults).
+     * In modular projects, legacy directories must not occur because it is not clear


In modular projects, legacy directories must not occur --> Legacy directories cannot be used in modular projects

elharo · 2026-02-10T12:29:20Z

impl/maven-core/src/main/java/org/apache/maven/project/DefaultProjectBuilder.java

                /*
                 * `sourceDirectory`, `testSourceDirectory` and `scriptSourceDirectory`
-                 * are ignored if the POM file contains at least one enabled <source> element
+                 * are not used if the POM file contains at least one enabled <source> element


again here don't we need the build to fail in this case?

Yes, I think that it is a change that was forgot in the documentation. The actual code raises an error as I read it.

Looking at this more closely, I think we've uncovered an inconsistency:

Current behavior:

Resources (<resources>/<testResources>): ERROR for both modular and classic projects when <sources> conflicts with legacy config (handled in SourceHandlingContext)

Source directories (<sourceDirectory>/<testSourceDirectory>): ERROR only for modular projects, silently skipped for classic projects

AC8 specifically scopes the error behavior to modular projects:

"Legacy directories trigger ERROR in modular projects"

This leaves classic projects with <sources> in an inconsistent state - their legacy resources cause an error, but legacy source directories are silently ignored.

Proposal: If @desruisseaux and @elharo agree, we could add:

AC9: For classic (non-modular) projects, legacy <sourceDirectory> and <testSourceDirectory> also trigger an ERROR when <sources> elements are configured for the same scope/language. This ensures consistency with resource handling and prevents silent configuration loss.

Should I create a follow-up issue for this, or would you prefer to extend the current PR?

Thanks for spotting that. I suggest to extend the current pull request if this is fine for you.

I'm not fully up to speed on all of this. I try to avoid modules. However, the general principle I would follow is that if the client project contains code or resources that the developer likely intended to be included and for some reason we are not including it, then Maven should hard fail the build.

Seems very good to me.

Seems very good to me.

OK, I will implement it this way then.

And yet another use case: Assume we have the following structure:

<build> <sources> <source> <scope>main</scope> <lang>resources</lang> <directory>src/main/custom-resources</directory> </source>  </sources> </build>

I would think in a legacy directory structure but 4.1.0-model configuration (but no modules), the legacy directories should still be (implicitly) used, unless explicitly overridden. What do you think, @desruisseaux ?

Said that: the classic values were defined as default by the super POM. Do we expect similar defaults by the super POM for <sources> as well (currently not configured)?

Yes, when the <module> element is not used I think that we can continue to use the legacy directories.

Regarding the default values specified in the super POM, I suggest to not do any change for now (we may revisit in some future version). The default values of <source> elements are implemented in Java code for now, and they are designed in such a way that, when no <module> element is used, they match the default values of the super POM.

OK, I fully agree that we should not require something on the Super POM by now but just use the classic directories as fallback if nothing is explicitly configured. Nevertheless, I will create a new Acceptance Criterion to express that design choice - we are back at (another) AC9 then 😉:

AC9 Definition (Non-Modular Projects)

AC9 (Legacy directory handling for non-modular projects):

For non-modular projects using <sources>:

When <sources> has Java for a scope: Legacy directories are rejected if they differ from the default (explicit configuration detected)

When <sources> has no Java for a scope: Legacy directories are used as implicit fallback only if they match the default (could be inherited)

I already made some progress implementing and testing this and will deliver test cases for both AC8 and AC9

ascheman · 2026-02-13T16:20:06Z

AC8 and AC9: Legacy Directory Handling with `<sources>`

Summary

This PR meanwhile covers two related acceptance criteria for handling legacy directories when <sources> is configured (cf. #11701 / AC8+9):

AC8 (Modular projects): ALL legacy directories are rejected
AC9 (Non-modular projects): Implicit fallback to legacy directories when <sources> doesn't configure that scope/language

Background

Originally AC8 was proposed to reject legacy directories in modular projects because content cannot be dispatched between modules. However, for non-modular projects using <sources>, there's a valid use case for incremental adoption: customize only specific source types (e.g., resources) while keeping the default Java directory structure.

AC8 Definition (Modular Projects)

AC8 (Legacy directory rejection for modular projects):

For modular projects (projects with <module> attribute in <source> elements), the build fails with an ERROR if:

An explicit legacy directory configuration (<sourceDirectory> or <testSourceDirectory>) exists that differs from the Super POM default, OR
The default legacy directory (e.g., src/main/java) exists physically on the filesystem

Rationale

In modular projects using paths like src/<module>/main/java, legacy directories like src/main/java cannot be dispatched between modules. Any content there would be silently ignored, so the build must fail.

AC9 Definition (Non-Modular Projects)

AC9 (Legacy directory handling for non-modular projects):

For non-modular projects using <sources>:

When <sources> has Java for a scope: Legacy directories are rejected if they differ from the default (explicit configuration detected)
When <sources> has no Java for a scope: Legacy directories are used as implicit fallback only if they match the default (could be inherited)

Behavior

`<sources>` contains	Legacy directory	Result
`<source><lang>java</lang><scope>main</scope></source>`	`<sourceDirectory>` differs	ERROR
`<source><lang>java</lang><scope>main</scope></source>`	`<sourceDirectory>` default	OK (ignored)
`<source><lang>resources</lang><scope>main</scope></source>` only	`<sourceDirectory>` differs	ERROR
`<source><lang>resources</lang><scope>main</scope></source>` only	`<sourceDirectory>` default	OK (used as fallback)

Rationale

This allows incremental adoption of <sources>:

Users can customize only specific source types (e.g., resources)
Default Java directories continue to work without explicit configuration
Explicit legacy overrides (differ from default) always trigger errors - this is detectable and indicates mixing of approaches

Example

<build>
  <sources>
    <!-- Only customize resources, keep default Java directories -->
    <source>
      <lang>resources</lang>
      <scope>main</scope>
      <directory>src/main/custom-resources</directory>
    </source>
  </sources>
  <!-- src/main/java is used implicitly (AC9) -->
</build>

Complete Test Matrix

#	Project Type	`<sources>` has Java?	Legacy differs?	Physical exists?	Result	AC	Test Project	Test Method
1	Classic	N/A	Any	Any	OK	-	-	(default behavior)
2	Modular	Yes	Yes	Any	ERROR	AC8	`modular-java-with-explicit-source-dir`	`testModularWithJavaSourcesRejectsLegacySourceDirectory`
3	Modular	Yes	No	Yes	ERROR	AC8	`modular-with-physical-legacy`	`testModularWithPhysicalDefaultLegacyDirectory`
4	Modular	Yes	No	No	OK	AC8	-	(happy path)
5	Modular	No	Yes	Any	ERROR	AC8	`modular-no-test-java-with-explicit-test-source-dir`	`testModularWithoutTestSourcesRejectsLegacyTestSourceDirectory`
6	Modular	No	No	Yes	ERROR	AC8	`modular-resources-only-with-physical-legacy`	`testModularResourcesOnlyWithPhysicalDefaultLegacyDirectory`
7	Modular	No	No	No	OK	AC8	-	(happy path)
8	Non-modular	Yes	Yes	Any	ERROR	AC9	`classic-sources-with-explicit-legacy`	`testClassicSourcesWithExplicitLegacyDirectories`
9	Non-modular	Yes	No	Any	OK	AC8	-	(happy path)
10	Non-modular	No	Yes	Any	ERROR	AC9	`non-modular-resources-only-explicit-legacy`	`testNonModularResourcesOnlyWithExplicitLegacyDirectoriesRejected`
11	Non-modular	No	No	Any	OK (fallback)	AC9	`non-modular-resources-only`	`testNonModularResourcesOnlyWithImplicitJavaFallback`

Legend

Project Type:
- Classic: No <sources> element configured
- Modular: <sources> has <source> elements with <module> attribute
- Non-modular: <sources> has <source> elements without <module> attribute
<sources> has Java?: Whether <sources> contains <source><lang>java</lang>...</source> for the scope being validated
Legacy differs?: Whether <sourceDirectory>/<testSourceDirectory> differs from Super POM default (src/main/java/src/test/java)

Limitation: Maven works with the effective model after inheritance resolution. It cannot distinguish whether a value matching the default was inherited (from Super POM or any parent) or explicitly configured. For modular projects, the physical presence check provides an additional safeguard.
Physical exists?: Whether the default legacy directory physically exists on the filesystem (only checked for modular projects)

Test Coverage Summary

Category	Tests
AC8 - Modular with explicit legacy	`testModularWithJavaSourcesRejectsLegacySourceDirectory`, `testModularWithoutTestSourcesRejectsLegacyTestSourceDirectory`
AC8 - Modular with physical presence	`testModularWithPhysicalDefaultLegacyDirectory`, `testModularResourcesOnlyWithPhysicalDefaultLegacyDirectory`
AC9 - Non-modular with Java in sources (legacy rejected)	`testClassicSourcesWithExplicitLegacyDirectories`
AC9 - Non-modular without Java in sources (implicit fallback)	`testNonModularResourcesOnlyWithImplicitJavaFallback`
AC9 - Non-modular without Java in sources (explicit rejected)	`testNonModularResourcesOnlyWithExplicitLegacyDirectoriesRejected`

Implementation

The implementation uses:

failIfLegacyDirectoryPresent method with checkPhysicalPresence parameter:
- true for modular projects (checks both config and filesystem)
- false for non-modular projects (checks only explicit config)
Conditional validation:
- Modular: Always validate both <sourceDirectory> and <testSourceDirectory>
- Non-modular: Validate each scope independently:
  - <sourceDirectory> is validated only if hasSources(JAVA_FAMILY, MAIN) returns true
  - <testSourceDirectory> is validated only if hasSources(JAVA_FAMILY, TEST) returns true
Implicit fallback:
- Non-modular without Java in <sources>: call addCompileSourceRoot()/addTestCompileSourceRoot()

Code Structure

if (sources.isEmpty()) {
    // Classic: use all legacy directories
    project.addScriptSourceRoot(build.getScriptSourceDirectory());
    project.addCompileSourceRoot(build.getSourceDirectory());
    project.addTestCompileSourceRoot(build.getTestSourceDirectory());
    sourceContext.handleResourceConfiguration(MAIN);
    sourceContext.handleResourceConfiguration(TEST);
} else {
    // Source roots from <sources> are added by SourceHandlingContext.processSourceElements()
    if (isModularProject) {
        // AC8: reject ALL legacy directories (both scopes)
        // (source roots come exclusively from <sources> elements)
        failIfLegacyDirectoryPresent(sourceDirectory, ..., checkPhysicalPresence=true);
        failIfLegacyDirectoryPresent(testSourceDirectory, ..., checkPhysicalPresence=true);
    } else {
        // Non-modular: always validate (error if differs from default)
        failIfLegacyDirectoryPresent(sourceDirectory, ..., checkPhysicalPresence=false);
        failIfLegacyDirectoryPresent(testSourceDirectory, ..., checkPhysicalPresence=false);

        // AC9 fallback: only if no Java in <sources> AND legacy matches default
        if (!hasSources(JAVA_FAMILY, MAIN) && matchesDefault(sourceDirectory)) {
            project.addCompileSourceRoot(build.getSourceDirectory());
        }
        if (!hasSources(JAVA_FAMILY, TEST) && matchesDefault(testSourceDirectory)) {
            project.addTestCompileSourceRoot(build.getTestSourceDirectory());
        }
    }
}

Issue Unified source handling for all lang/scope combinations with modular sources (Phase 2) #11612: Unified source handling for all lang/scope combinations
Issue Legacy resources in modular build should fail #11701: Legacy resources in modular build should fail
Confluence: Original Build Sources Validation - Discussion in Confluence (outdated as of 2026-02-13)

In modular projects, legacy directories and resources that would be silently ignored now trigger an ERROR instead of WARNING: - Explicit <sourceDirectory>/<testSourceDirectory> differing from defaults - Default src/main/java or src/test/java existing on filesystem - Explicit <resources>/<testResources> differing from Super POM defaults This prevents silent loss of user-configured sources/resources. AC8 supersedes AC7 which originally used WARNING. Fixes apache#11701 See apache#11701 (comment) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Use "cannot" instead of "must not" in error messages - Update Javadoc: "The build fails" instead of "A warning is emitted"

AC8 (modular projects): - Reject all legacy directories when <sources> is configured - Check physical presence of default directories (src/main/java) AC9 (non-modular projects): - Reject legacy directories when <sources> has Java for that scope - Allow implicit fallback only when legacy matches default Split test projects for clearer scenario coverage. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

impl/maven-core/src/main/java/org/apache/maven/project/DefaultProjectBuilder.java

Use File.separator in test assertions for platform-independent path matching instead of normalizing paths in production code. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

ascheman force-pushed the bugfix/11701-fail-on-modular-sources-with-legacy-dirs branch from 70a7358 to c1b431b Compare February 6, 2026 10:05

ascheman marked this pull request as ready for review February 6, 2026 13:27

elharo requested changes Feb 6, 2026

View reviewed changes

desruisseaux approved these changes Feb 8, 2026

View reviewed changes

elharo requested changes Feb 10, 2026

View reviewed changes

ascheman mentioned this pull request Feb 11, 2026

Legacy resources in modular build should fail #11701

Open

desruisseaux mentioned this pull request Feb 13, 2026

Add module-aware resource handling for modular sources #11700

Open

ascheman and others added 3 commits February 14, 2026 12:16

Address review feedback on wording

90c344e

- Use "cannot" instead of "must not" in error messages - Update Javadoc: "The build fails" instead of "A warning is emitted"

ascheman force-pushed the bugfix/11701-fail-on-modular-sources-with-legacy-dirs branch from 4cfb6e9 to befcf4a Compare February 14, 2026 11:18

desruisseaux reviewed Feb 14, 2026

View reviewed changes

impl/maven-core/src/main/java/org/apache/maven/project/DefaultProjectBuilder.java Outdated Show resolved Hide resolved

Fix Windows test failures for physical legacy directory check

60faffc

Use File.separator in test assertions for platform-independent path matching instead of normalizing paths in production code. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

ascheman force-pushed the bugfix/11701-fail-on-modular-sources-with-legacy-dirs branch from afe0e1e to 60faffc Compare February 14, 2026 13:16

ascheman mentioned this pull request Feb 14, 2026

Consumer POM of multi-module project should exclude <build> and <dependencies> elements #11639

Open

Conversation

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

Uh oh!

Summary

Test plan

Uh oh!

ascheman commented Feb 6, 2026

Uh oh!

elharo left a comment

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!

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!

ascheman Feb 12, 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!

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

Uh oh!

Choose a reason for hiding this comment

AC9 Definition (Non-Modular Projects)

Uh oh!

ascheman commented Feb 13, 2026

AC8 and AC9: Legacy Directory Handling with <sources>

Summary

Background

AC8 Definition (Modular Projects)

Rationale

AC9 Definition (Non-Modular Projects)

Behavior

Rationale

Example

Complete Test Matrix

Legend

Test Coverage Summary

Implementation

Code Structure

Related

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

ascheman commented Feb 6, 2026 •

edited

Loading

ascheman Feb 12, 2026 •

edited

Loading

ascheman Feb 13, 2026 •

edited

Loading

AC8 and AC9: Legacy Directory Handling with `<sources>`