(maven) 01/01: Fix #11504: add replacement guidance to deprecated model and settings APIs

[gn...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

gnodet pushed a commit to branch fix-11504
in repository https://gitbox.apache.org/repos/asf/maven.git

commit 23ae7ae893d1d3db8e8605d422183439793688a6
Author: Guillaume Nodet <gn...@gmail.com>
AuthorDate: Thu Aug 27 20:46:13 2026 +0200

    Fix #11504: add replacement guidance to deprecated model and settings APIs
    
    Update @deprecated Javadoc tags in maven.mdo and settings.mdo to tell
    users what to use instead of each deprecated element:
    
    - Notifier.address → use the configuration properties map
    - Model.getProjectDirectory() → use getProjectDirectoryPath()
    - ModelBase.reports → use the reporting element
    - ConfigurationContainer.unsetInheritanceApplied() → no-op, no replacement
    - ConfigurationContainer.setInherited(boolean) → use setInherited(String)
    - Plugin.goals → use executions
    - Plugin.flushExecutionMap() → no-op, no replacement
    - Reporting.flushReportPluginMap() → no-op, no replacement
    - Settings.getMirrorOf() → use mirror matching infrastructure
    
    Co-Authored-By: Claude Opus 4.6 <no...@anthropic.com>
---
 api/maven-api-model/src/main/mdo/maven.mdo       | 17 ++++++++++++++---
 api/maven-api-settings/src/main/mdo/settings.mdo |  4 ++++
 2 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/api/maven-api-model/src/main/mdo/maven.mdo b/api/maven-api-model/src/main/mdo/maven.mdo
index c5057ade7c..243b784e2a 100644
--- a/api/maven-api-model/src/main/mdo/maven.mdo
+++ b/api/maven-api-model/src/main/mdo/maven.mdo
@@ -435,6 +435,7 @@
      *
      * @return The base directory for the corresponding project or {@code null} if this model does not belong to a local
      *         project (e.g. describes the metadata of some artifact from the repository).
+     * @deprecated Use {@link #getProjectDirectoryPath()} instead, which returns a {@link java.nio.file.Path}.
      */
     @Deprecated
     public java.io.File getProjectDirectory() {
@@ -641,7 +642,7 @@
           <name>reports</name>
           <version>4.0.0</version>
           <description>
-            @deprecated Now ignored by Maven.
+            @deprecated Now ignored by Maven. Use the {@code reporting} element to configure report plugins instead.
           </description>
           <type>DOM</type>
           <annotations>
@@ -1078,7 +1079,7 @@
           <version>4.0.0+</version>
           <type>String</type>
           <description>
-            @deprecated Where to send the notification to - eg email address.
+            @deprecated Use the {@code configuration} properties map to specify the notification address instead.
           </description>
           <annotations>
             <annotation>@Deprecated(since = "4.0.0")</annotation>
@@ -2597,10 +2598,16 @@
           <version>4.0.0/4.0.99</version>
           <code>
             <![CDATA[
+    /**
+     * @deprecated This method is a no-op and has no replacement.
+     */
     @Deprecated
     public void unsetInheritanceApplied() {
     }
 
+    /**
+     * @deprecated Use {@link #setInherited(String)} instead.
+     */
     @Deprecated
     public void setInherited(boolean value) {
       setInherited(Boolean.toString(value));
@@ -2663,7 +2670,7 @@
           <name>goals</name>
           <version>4.0.0</version>
           <description>
-            @deprecated Unused by Maven.
+            @deprecated Unused by Maven. Use {@code executions} to configure plugin goals instead.
           </description>
           <type>DOM</type>
           <annotations>
@@ -2702,6 +2709,8 @@
 
     /**
      * Reset the {@code executionMap} field to {@code null}
+     *
+     * @deprecated This method is a no-op and has no replacement.
      */
      @Deprecated
     public void flushExecutionMap() {
@@ -2934,6 +2943,8 @@
 
     /**
      * Reset the <code>reportPluginMap</code> field to <code>null</code>
+     *
+     * @deprecated This method is a no-op and has no replacement.
      */
     @Deprecated
     public void flushReportPluginMap() {
diff --git a/api/maven-api-settings/src/main/mdo/settings.mdo b/api/maven-api-settings/src/main/mdo/settings.mdo
index 0e8803b2d4..b9f37bda22 100644
--- a/api/maven-api-settings/src/main/mdo/settings.mdo
+++ b/api/maven-api-settings/src/main/mdo/settings.mdo
@@ -293,6 +293,10 @@
         return match;
     }
 
+    /**
+     * @deprecated This simplistic lookup does not support advanced mirror matching syntax.
+     * There is no direct replacement; use the Maven mirror matching infrastructure instead.
+     */
     @Deprecated
     public Mirror getMirrorOf(String repositoryId) {
         Mirror match = null;