Proposal: Deprecate resource autodetection in favor of authored reachability metadata

[vjovanov]

Note

This is a design proposal for discussion, not an accepted plan or committed work.

Summary

Deprecate Native Build Tools resource autodetection and its generated legacy resource-config.json surface. Do not replace it with another classpath-scanning generator. Instead, guide users toward source-controlled reachability-metadata.json using folder-scoped resource globs, while relying on Native Image's static detection when resource lookups are constant.

This applies symmetrically to:

• Maven native:generateResourceConfig and native:generateTestResourceConfig
• Gradle generateResourcesConfigFile, test, and custom-binary variants
• the associated resources.autodetection.* Maven properties and Gradle resource-autodetection DSL

Motivation

Resource autodetection duplicates metadata authoring in the build-tool layer. It scans selected classpath entries, maintains filtering and existing-config rules, serializes the legacy resource-config.json format, and wires generated output into Native Image. This creates a second resource-metadata abstraction that Native Build Tools must maintain as Native Image metadata evolves.

Native Image now supports resources directly in the unified reachability-metadata.json format. For most applications, a small number of stable folder-scoped globs expresses intent more clearly than a generated inventory of individual files. A global ** glob is not valid, but one glob per resource folder is sufficient; root-level resources can be listed explicitly.

For example:

{
  "resources": [
    { "glob": "config/**" },
    { "glob": "templates/**" },
    { "glob": "banner.txt" }
  ]
}

This metadata belongs under META-INF/native-image/<groupId>/<artifactId>/reachability-metadata.json and is picked up directly by Native Image. Keeping it in source control makes resource inclusion reviewable, predictable, and independent of Gradle/Maven task execution.

Proposed migration

1. Prefer Native Image behavior

Document the following order of preference:

1. No metadata when Native Image can infer a constant resource lookup.
2. Authored reachability-metadata.json with one glob per resource folder, plus exact entries for root-level resources.
3. Tracing/metadata collection when the required resources depend on runtime behavior and cannot be described confidently up front.

2. Deprecate without introducing a replacement generator

Do not add a generateReachabilityMetadata task or goal. That would preserve the same classpath scanner and maintenance burden under a new output format.

During the deprecation period:

• existing tasks/goals continue to work and emit their current output;
• enabling autodetection or invoking a generation entry point emits an actionable warning;
• the warning links to migration documentation and names the major version in which removal is planned;
• existing include/exclude regex behavior remains unchanged, because arbitrary Java regular expressions cannot be translated safely to the restricted glob grammar;
• generated output continues to be consumed as before, so minor/patch upgrades do not break builds.

Remove the deprecated tasks/goals, DSL/XML/properties, scanner, and legacy serializer only at a major-version boundary, consistent with §root/REQ-backwards-compatibility.

3. Keep -H:Preserve separate

-H:Preserve is not the replacement for resource metadata. It preserves classes/packages/modules/classpath entries that closed-world analysis would otherwise remove; ordinary resource inclusion remains expressed by the resources section of reachability-metadata.json.

#978 remains a related but independent proposal. Its build-tool-specific value is resolving dependency coordinates to path=<resolved-entry>. This deprecation should neither depend on #978 nor add resource-scanning semantics to -H:Preserve.

Compatibility considerations

• The currently declared Native Image floor must support the unified resource metadata used by the migration guide (§root/REQ-support-matrix).
• Legacy include/exclude regexes and ignoreExistingResourcesConfig do not have lossless unified-metadata equivalents; they remain supported until removal rather than being silently rewritten.
• Projects that intentionally generate resource sets from changing dependency graphs can stay on the deprecated behavior during the transition and should provide concrete use cases if authored folder globs are insufficient.
• Main, test, and custom-binary behavior must follow the same policy in Maven and Gradle (§root/GOAL-plugin-parity).

Spec impact

Spec changes must precede implementation:

• revise §root/FS-resources-and-metadata.1;
• revise §common/FS-common-libraries.2;
• revise §gradle/FS-resources-and-metadata.1 and .2;
• revise §maven/FS-resources-and-metadata.1 and .5;
• add the deprecation/removal boundary to the relevant Gradle and Maven goal/task surface specs.

Acceptance criteria

• Migration documentation shows valid folder-scoped unified metadata and exact root-file entries.
• Documentation explains when Native Image needs no explicit resource metadata.
• Documentation clearly states that -H:Preserve does not replace resource metadata.
• All Maven and Gradle resource-autodetection entry points emit consistent deprecation warnings.
• Existing behavior and output remain compatible throughout the deprecation period.
• Functional tests cover the warnings and continued compatibility.
• Removal is scheduled only for a major release.
• Proposal: Add -H:Preserve support via the shared ArtifactSelection model #978 is cross-linked as related, not as a prerequisite.

Open questions

1. Which major release should remove the deprecated surface?
2. Are there important dependency-driven resource layouts that cannot be maintained reasonably with one authored glob per folder?
3. Should the migration guide recommend module-qualified resource entries for modular applications?