Document deprecations in PrepareReleaseMojo and PerformReleaseMojo

maven-release-manager/src/main/java/org/apache/maven/shared/release/transform/ModelETL.java

@@ -51,11 +51,18 @@ public interface ModelETL {
      */
     void load(File pomFile) throws ReleaseExecutionException;
 
-    // will be removed once transform() is implemented
     /**
-     * <p>getModel.</p>
+     * Returns the intermediate {@link Model} representation.
      *
-     * @return a {@link org.apache.maven.model.Model} object
+     * @deprecated This method is a temporary accessor that exists only for
+     *             legacy workflow support. It will be removed once the
+     *             {@link #transform()} processing phase is fully implemented
+     *             and callers no longer need to access the intermediate model
+     *             directly.
+     *
+     *             There is no direct replacement. New code should rely on the
+     *             {@link #extract(File)} -> {@link #transform()} -> {@link #load(File)}
+     *             processing pipeline instead of accessing the model explicitly.
      */
     @Deprecated
     Model getModel();

maven-release-plugin/src/main/java/org/apache/maven/plugins/release/PerformReleaseMojo.java

@@ -86,15 +86,22 @@ public class PerformReleaseMojo extends AbstractScmReadReleaseMojo {
     private boolean localCheckout;
 
     /**
-     * Whether to use the default release profile (Maven 2 and 3) that adds sources and javadocs to the released
-     * artifact, if appropriate. If set to true, the release plugin sets the property "<code>performRelease</code>" to
-     * true, which activates the profile "<code>release-profile</code>" as inherited from
-     * <a href="/ref/3.8.5/maven-model-builder/super-pom.html">the super pom</a>.
+     * Whether to use the default {@code release-profile} from the Maven
+     * super POM (Maven 2 and 3), which adds sources and javadocs to the
+     * released artifacts when appropriate.
      *
-     * @deprecated The <code>release-profile</code> profile will be removed from future versions of the super POM
+     * @deprecated The {@code release-profile} will be removed from future
+     *             versions of the Maven super POM and should no longer be
+     *             relied upon. Projects that require specific release
+     *             behavior should configure their own explicit build or
+     *             release profiles instead of depending on this implicit
+     *             profile.
+     *
+     *             This parameter will be removed in a future version of the
+     *             plugin.
      */
-    @Parameter(defaultValue = "false", property = "useReleaseProfile")
     @Deprecated
+    @Parameter(defaultValue = "false", property = "useReleaseProfile")
     private boolean useReleaseProfile;
 
     /**

maven-release-plugin/src/main/java/org/apache/maven/plugins/release/PrepareReleaseMojo.java

@@ -62,7 +62,16 @@ public class PrepareReleaseMojo extends AbstractScmReadWriteReleaseMojo {
     private boolean resume;
 
     /**
-     * @deprecated Please use release:prepare-with-pom instead.
+     * Controls whether the plugin should generate release POMs during the
+     * prepare phase.
+     *
+     * @deprecated This flag is no longer the preferred way to perform a
+     *             release. Use the dedicated {@code release:prepare-with-pom}
+     *             goal instead, which provides a clearer and more explicit
+     *             workflow for preparing releases that require generated POMs.
+     *
+     *             This parameter will be removed in a future version of the
+     *             plugin.
      */
     @Deprecated
     @Parameter(defaultValue = "false", property = "generateReleasePoms")